Dokumentaatiogeneraattori - ohjelma tai ohjelmistopaketti, jonka avulla voit hankkia ohjelmoijille ( API - dokumentaatio ) ja/tai järjestelmän loppukäyttäjille tarkoitettua dokumentaatiota erityisesti kommentoidun lähdekoodin ja joissakin tapauksissa suoritettavien moduulien (saatavissa osoitteessa kääntäjän lähtö ).
Yleensä generaattori analysoi ohjelman lähdekoodia ja tuo esiin ohjelman merkittäviä objekteja vastaavat syntaktiset rakenteet (tyypit, luokat ja niiden jäsenet/ominaisuudet/metodit, menettelyt/funktiot jne.). Analyysissä käytetään myös ohjelmaobjektien metatietoa, joka esitetään dokumentoivien kommenttien muodossa. Kaikkien kerättyjen tietojen perusteella valmis dokumentaatio muodostetaan pääsääntöisesti johonkin yleisesti hyväksytyistä muodoista - HTML , HTMLHelp , PDF , RTF ja muut.
Asiakirjakommentti on erityisesti muotoiltu kommentti ohjelmaobjektiin, jota tietty dokumentaatiogeneraattori käyttää. Dokumentaation kommenteissa käytettyjen konstruktien syntaksi riippuu käytetystä dokumentaatiogeneraattorista .
Dokumentaatiokommentit voivat sisältää tietoa koodin tekijästä, kuvata ohjelmaobjektin tarkoitusta, toiminnon/proseduurin syöttö- ja lähtöparametrien merkitystä, käyttöesimerkkejä, mahdollisia poikkeuksia ja toteutusominaisuuksia.
Dokumentaatiokommentit muotoillaan yleensä monirivisiksi C -tyylisiksi kommenteiksi . Kussakin tapauksessa kommentin on tultava ennen dokumentoitua elementtiä. Kommentin ensimmäisen merkin (ja kommenttirivien alussa) on oltava *. Lohkot erotetaan tyhjillä viivoilla.
Esimerkki dokumentaarisesta kommentista PHP :llä:
/** * Objektin nimi tai lyhyt kuvaus * * Pitkä kuvaus * * @descriptor_name value * @return data_type */| Luettelo phpDocumentor- kahvoista | ||
|---|---|---|
| Kuvaaja | Kuvaus | Esimerkki |
| @author | Tekijä | /** * Esimerkkitiedosto 2, phpDocumentor Quickstart * * Tiedosto phpDocumentor dokumentaatiosta *, joka näyttää kuinka kommentoida. * @author Greg Beaver <[email protected]> * @versio 1.0 * @package sample * @subpackage classes */ |
| @version | Koodi versio | |
| @package | Määrittää paketin, johon koodi kuuluu | |
| @subpackage | Määrittää alipaketin | |
| @global | Globaalien muuttujien kuvaus | /** * DocBlock globaalille muuttujalle * @global integer $GLOBALS['myvar'] ja sen jälkeen funktio globaalilla muuttujalla * tai globaalilla muuttujalla, jolloin sinun on määritettävä sen nimi * @nimi $myvar */ $ GLOBAALIT [ 'myvar' ] = 6 ; |
| @name | Nimi, etiketti | |
| @staticvar | Staattisten muuttujien kuvaus | /** * @staticvar kokonaisluku $staticvar * @return palauttaa kokonaisluvun */ |
| @return | Palautusarvon kuvaus | |
| @todo | Huomautuksia myöhempää käyttöönottoa varten. | /** * DocBlock sisäkkäisillä luetteloilla * @todo Yksinkertainen TODO-lista * - kohde 1 * - kohde 2 * - kohde 3 * @todo Sisäkkäinen TODO-luettelo * <ol> * <li>kohde 1.0</li> * <li> kohde 2.0</li> * <ol> * <li>tuote 2.1</li> * <li>kohde 2.2</li> * </ol> * <li>kohde 3.0</li> * </ol> */ |
| @link | Linkki | /** * Tämä on esimerkki {@link http://www.example.com upotetusta hyperlinkistä} */ |
| @deprecated (@deprec) | Kuvaus vanhentuneesta lohkosta | /** * @deprecated description * @deprec on synonyymi sanalle vanhentunut */ |
| @example | Esimerkki | /** * @abstract * @pääsy julkinen tai yksityinen * @copyright nimi päivämäärä * @esimerkki /polku/esimerkki * @ohita * @sisäiset yksityiset tiedot asiantuntijoille * @param type [$varname] syöttöparametrin kuvaus * @return tyyppi palautusarvon kuvaus * @katso muun elementin nimi (viite) * @versiosta tai päivämäärästä * @static */ |
| @see | Linkki toiseen paikkaan dokumentaatiossa | |
| Muut kuvailevat | ||
| @copyright • @license • @filesource • @category • @since • @abstract • @access • @example • @ignore • @internal • @static • @throws • @uses • @tutorial | ||
Esimerkki doc - kommentista Java - ohjelman funktiolle , joka on tarkoitettu Javadocin käyttöön :
/** * Tarkistaa, onko muutto voimassa. * Jos esimerkiksi haluat asettaa siirron e2-e4, kirjoita isValidMove(5,2,5,4); * @author John Doe * @param theFromFile Pystysuora, jossa muoto on (1=a, 8=h) * @param theFromRank Vaaka, jossa muoto on (1...8) * @param theToFile Pysty, jossa muoto on is siirto suoritetaan (1=a, 8=h) * @param theToRank Sen solun vaakasuunta, johon siirretään (1...8) * @return tosi jos siirto on kelvollinen ja false jos se ei kelpaa */ boolean isValidMove ( int theFromFile , int theFromRank , int theToFile , int theToRank ) { . . . }Esimerkkejä eri kielistä ja ohjelmointiympäristöistä: