1. Avaa Doxygenin lataussivu: https://www.doxygen.nl/download.html.
2. Lataa Windowsille tarkoitettu asennuspaketti ja asenna Doxygen.
3. Avaa Graphvizin lataussivu: https://graphviz.org/download/.
4. Lataa ja asenna Windows-versio Graphvizista.
5. Jos asennusohjelma ei lisää ohjelmia automaattisesti Windowsin PATH-ympäristömuuttujaan, lisää tarvittaessa Doxygenin ja Graphvizin asennuskansiot PATH-muuttujaan. Graphvizin komentorivityökalu on yleensä nimeltään dot.exe ja sijaitsee Graphvizin bin-kansiossa.
6. Avaa uusi komentokehote (Command Prompt) ja tarkista asennukset komennoilla:

   doxygen --version
   dot -V

   Molempien komentojen pitäisi tulostaa ohjelman versiotiedot. Jos komentoa ei löydy, tarkista asennuspolku ja PATH-asetus.

Doxygenin avainsanat kirjoitetaan dokumentointikommenttiin, esimerkiksi /** ... */ tai ///. Sijoita kommentti heti sen luokan tai metodin esittelyn eteen, jota se kuvaa. Avainsana alkaa @-merkillä.

• @brief antaa lyhyen yhteenvedon luokan tai metodin tarkoituksesta.
• @details aloittaa tarkemman kuvauksen. Lisätietoja voi kirjoittaa myös ilman tätä avainsanaa jättämällä tyhjän rivin lyhyen kuvauksen jälkeen.
• @param nimi kuvaus kuvaa metodin parametrin. Nimen täytyy vastata koodissa käytettyä parametrin nimeä. Jokainen parametri kuvataan erikseen. Tarvittaessa suunnan voi merkitä muodossa @param[in], @param[out] tai @param[in,out].
• @return kuvaa metodin palauttaman arvon merkityksen. Sitä ei tarvita void-metodille eikä konstruktorille.
• @retval arvo kuvaus selittää yksittäisen paluuarvon, esimerkiksi @retval true Nimi vaihdettiin onnistuneesti.
• @throws poikkeustyyppi kuvaus kertoo, minkä poikkeuksen metodi voi heittää ja missä tilanteessa.
• @note lisää huomautuksen tai käyttöä helpottavan lisätiedon.
• @warning korostaa käyttöön liittyvää varoitusta.
• @see viittaa aiheeseen liittyvään luokkaan tai metodiin, esimerkiksi @see getName().
• @todo merkitsee vielä tehtävän työn dokumentaatioon.
• @deprecated kertoo, että kohteen käyttöä ei enää suositella. Kuvauksessa kannattaa mainita korvaava toiminto.

Esimerkiksi setterin dokumentointi voi näyttää tältä:

/**
 * @brief Muuttaa henkilön nimen.
 * @param newName Henkilön uusi nimi.
 * @see getName()
 */
void setName(const string &newName);

Kaikkia avainsanoja ei tarvitse käyttää jokaisessa kommentissa. Valitse ne, jotka auttavat ymmärtämään dokumentoitavan kohteen käyttöä. Katso myös Doxygenin avainsanojen täydellinen luettelo.

Tässä esimerkissä tutustutaan Doxygenin ja Graphvizin käyttöön tavallisen C++-sovelluksen dokumentoinnissa. Samoja työkaluja voidaan käyttää myös Qt-sovellusten dokumentointiin.

1. Luo Non-Qt Project → Plain C++ Application. Anna projektin nimeksi PersonDemo.
2. Lisää Person luokka ja siihen:
   1. private string nimeltään name
   2. public getter ja setter namelle
3. Lisää person.h tiedostoon kommentit seuraavasti:

   #ifndef PERSON_H
   #define PERSON_H
   #include <iostream>
   using namespace std;
   
   /**
    * @brief Represents a Person of the application.
    *
    * Stores the Person's name and provides operations
    * for reading and updating it.
    */
   
   class Person
   {
   public:
       /**
        * @brief Constructs a Person.
        */
       Person();
       /**
        * @brief Returns the Person's name.
        * @return The current Person name.
        */
       string getName() const;
       /**
        * @brief Changes the Person's name.
        * @param newName The new Person name.
        */
       void setName(const string &newName);
   
   private:
       string name;
   };
   
   #endif // PERSON_H
   

Tiedostoon person.cpp ei tarvitse tehdä muutoksia.
4. Luo Doxygenin asetustiedosto (Doxyfile):
1. Avaa Windowsin komentokehote projektin juurikansioon
2. Luo Doxygenin asetustiedosto komennolla:

   doxygen -g Doxyfile

   Tämä luo projektin juureen tiedoston nimeltä Doxyfile.
3. Avaa Doxyfile tekstieditorissa, esimerkiksi Qt Creatorissa tai Muistiossa.
5. Muokkaa Doxyfile-asetuksia

   Etsi Doxyfilesta alla luetellut asetukset ja muuta niiden arvot. Asetukset voivat sijaita eri kohdissa tiedostoa. Muokkaa olemassa olevia rivejä; älä lisää samasta asetuksesta useita ristiriitaisia rivejä.

   PROJECT_NAME           = "PersonDemo"
   OUTPUT_DIRECTORY       = docs-generated
   INPUT                  = .
   RECURSIVE              = YES
   FILE_PATTERNS          = *.h *.cpp
   EXCLUDE_PATTERNS       = */build/* */docs-generated/*
   GENERATE_HTML          = YES
   GENERATE_LATEX         = NO
   EXTRACT_ALL            = YES
   EXTRACT_PRIVATE        = YES
   HIDE_UNDOC_MEMBERS     = NO
   WARN_IF_UNDOCUMENTED   = YES
   HAVE_DOT               = YES
   UML_LOOK               = YES

   • PROJECT_NAME määrittää dokumentaation projektinimen.
   • OUTPUT_DIRECTORY määrittää, minne tulosteet tallennetaan.
   • INPUT = . käskee tutkia nykyisen kansion. RECURSIVE = YES ottaa mukaan myös alikansiot.
   • FILE_PATTERNS rajaa tarkasteltavat tiedostot C++-otsake- ja lähdetiedostoihin.
   • EXCLUDE_PATTERNS jättää rakennus- ja tulostuskansiot käsittelyn ulkopuolelle. Jos projektisi rakennuskansion nimi on jokin muu, lisää se tarvittaessa tähän.
   • GENERATE_HTML = YES ottaa HTML-dokumentaation käyttöön.
   • GENERATE_LATEX = NO poistaa LaTeX-tulosteen käytöstä, koska tässä kokeessa tarvitaan vain HTML.
   • EXTRACT_ALL = YES ottaa mukaan myös kohteita, joilta puuttuu dokumentointikommentti. Kommentit näkyvät silti niiden kohdalla, joille olet kirjoittanut ne.
   • EXTRACT_PRIVATE = YES ottaa mukaan myös luokan private-jäsenet. Oletusarvo on NO, eikä EXTRACT_ALL = YES yksin ota niitä mukaan. Asetus mahdollistaa myös yksityisenä jäsenenä olevan olion koostesuhteen näkymisen yhteistyökaaviossa (COLLABORATION_GRAPH = YES), joten oliota ei tarvitse muuttaa public-jäseneksi kaaviota varten. Generoi dokumentaatio asetuksen muuttamisen jälkeen uudelleen komennolla doxygen Doxyfile.
   • HIDE_UNDOC_MEMBERS = NO sallii dokumentoimattomien jäsenten näyttämisen.
   • WARN_IF_UNDOCUMENTED = YES pyytää Doxygenia ilmoittamaan dokumentoimattomista kohteista.
   • HAVE_DOT = YES sallii Graphvizin käytön kaavioiden generointiin.
   • UML_LOOK = YES muuttaa Doxygenin tuottamien luokkakaavioiden ulkoasua UML-tyylisemmäksi silloin, kun kaavioita generoidaan.
6. Generoi dokumentaatio komennolla:

   doxygen Doxyfile

7. Seuraa komentokehotteen tulostetta. Jos Doxygen ilmoittaa virheistä tai varoituksista, tarkista ilmoitettu tiedosto ja rivi.
8. Avaa selaimessa projektin kansiosta tiedosto docs-generated/html/index.html.
9. Avaa dokumentaatiosta luokkaluettelo ja valitse Person. Sivulla pitäisi näkyä luokan kuvaus sekä metodit getName() ja setName().

Doxygenin generointi ei edellytä C++-ohjelman uudelleenkääntämistä. Kun muutat lähdekoodin dokumentointikommentteja, aja vain doxygen Doxyfile uudelleen.

Kokeile lisätä esimerkkiin perintää ja koostetta ja testaa, näkyvätkö ne diagrammissa.

Huomaa: Jos koostettava olio on private-jäsen, varmista, että Doxyfilessa on asetus EXTRACT_PRIVATE = YES, jotta koostesuhde näkyy diagrammissa.

Jos metodit eivät näy dokumentaatiossa

1. Tarkista, että Person.h sisältää metodien getName() ja setName() esittelyt luokan public:-osassa.
2. Tarkista, että Doxyfilen INPUT-asetus osoittaa kansioon, jossa Person.h sijaitsee.
3. Varmista, ettei Person.h ole poissuljettu EXCLUDE- tai EXCLUDE_PATTERNS-asetuksilla.
4. Aja uudelleen doxygen Doxyfile ja avaa generoitu HTML-sivu uudelleen.
5. Jos haluat luokkakaavioita, tarkista komennolla dot -V, että Graphviz on käytettävissä. Tavallisen luokka- ja metodidokumentaation luomiseen Graphvizia ei tarvita.

Lisätietoja

• Doxygenin käyttöohje
• Doxygenin lataussivu
• Graphvizin lataussivu