Doxygen
Mureakuha
Doxygen on lähdekoodin dokumentointityökalu. Tuettujen kielien listalla on mm. C/C++/Java/Python IDL, sekä joiltakin osin PHP, C# ja D. Ohjelmalla pystytään luomaan käyttökelpoinen API-dokumentaatio kommenteista, ja samalla se pakottaa käyttäjän noudattamaan kunnollista kommentointityyliä.
Ohjelmasta tuli ensimmäinen versio vuonna 1997, jonka jälkeen doxygeniä on kehitetty rajusti eteenpäin.
Kommentoimiseen käytetään omaa tyyliään jossa on erilaisia merkintöjä asioiden korostamiseen. Doxygen parsii lähdekoodin ja luo sen perusteella dokumentaation. Vaihtoehtoisista tulostuksista käytetään useimmiten HTML-muotoista dokumenttia, mutta myös chm, rtf, pdf, latex, postscript ja man-muotoista dokumentaatiota on mahdollista luoda.
Doxygenin tukemia dokumentointityylejä on useita joista kannattaa valita itselleen sopivin tyyli. Monissa kehitysympäristöissä on myös Doxygen-tuki jolla dokumentatio voidaan luoda yhdellä pikanäppäimelle, ja hyödyntää myös ohjelmoidessa, esim. "intellisense"-toiminto näyttää funktioiden kuvaukset.
Esimerkki:
/** * Find greatest common divisor. * @param[in] num1 Number 1. * @param[in] num2 Number 2. * @see lcd() * @return Greatest common divisor. */ int gcd(int num1, num2);
Doxygen tuntee kahdenlaisia kuvauksia. Lyhyen kuvauksen, joka esittelee toimintaidean ja on yhden lauseen mittainen, sekä selittävän kuvauksen jonka tarkoituksena olisi selittää asia tarkemmin. Tarkentava kuvaus jatkuu ensimmäisen lauseen jälkeen.
Parametri tagia käyttämällä kerrotaan tietoja parametrista. Se onko parametri tietoa syöttävä tai antava tai kumpaakin voidaan ilmaista käyttäen param sanan jälkeen hakasulkeita ja sopivaa ilmaisua [in] [out] [in,out]. Parametrin suunnan ilmaiseminen ei ole välttämätöntä, mutta suositeltavaa. Sen jälkeen tulee varsinainen parametrin nimi, jonka jälkeen tulee kuvaus parametrista.
See tagilla voidaan viitata johnonkin toiseen metodiin dokumentaatiossa. Jos on tarvetta viitata useisiin funktioihin, niin ne kannattaa ryhmitellä omaksi ryhmäkseen.
Return kertoo mitä arvoja metodi tai funktio palauttaa. Useat return lauseet dokumentaatiossa yhdistetään yhdeksi kuvaukseksi.
