Generátor dokumentace - program nebo softwarový balík , který umožňuje získat dokumentaci určenou programátorům ( API dokumentace ) a/nebo koncovým uživatelům systému podle speciálně komentovaného zdrojového kódu a v některých případech i spustitelných modulů (získaných na výstup kompilátoru ).
Generátor obvykle analyzuje zdrojový kód programu a zvýrazňuje syntaktické konstrukce odpovídající významným objektům programu (typy, třídy a jejich členy/vlastnosti/metody, procedury/funkce atd.). Analýza využívá také metainformace o objektech programu, prezentované formou dokumentujících komentářů. Na základě všech shromážděných informací se vytvoří hotová dokumentace zpravidla v jednom z obecně uznávaných formátů - HTML , HTMLHelp , PDF , RTF a další.
Komentář dokumentu je speciálně formátovaný komentář k objektu programu pro použití specifickým generátorem dokumentace. Syntaxe konstrukcí použitých v komentářích k dokumentaci závisí na použitém generátoru dokumentace .
Komentáře k dokumentaci mohou obsahovat informace o autorovi kódu, popisovat účel objektu programu, význam vstupních a výstupních parametrů pro funkci/proceduru, příklady použití, možné výjimky a implementační funkce.
Komentáře k dokumentaci jsou obvykle formátovány jako víceřádkové komentáře ve stylu C. V každém případě musí komentář předcházet dokumentovanému prvku. První znak v komentáři (a na začátku řádků komentáře) musí být *. Bloky jsou odděleny prázdnými řádky.
Příklad dokumentárního komentáře v PHP :
/** * Název objektu nebo krátký popis * * Dlouhý popis * * Hodnota @descriptor_name * @return data_type */| Seznam úchytů phpDocumentor | ||
|---|---|---|
| Deskriptor | Popis | Příklad |
| @author | Autor | /** * Ukázkový soubor 2, rychlý start phpDocumentor * * Soubor z dokumentace phpDocumentor *, který ukazuje, jak komentovat. * @author Greg Beaver <[email protected]> * @verze 1.0 * @ukázka balíčku * @třídy podbalíčků */ |
| @version | Verze kódu | |
| @package | Určuje balíček, ke kterému kód patří | |
| @subpackage | Určuje dílčí balíček | |
| @global | Popis globálních proměnných | /** * DocBlock pro globální proměnnou * @global integer $GLOBALS['myvar'] následovaný funkcí s globální proměnnou * nebo globální proměnnou, v takovém případě musíte zadat její název * @name $myvar */ $ GLOBÁLNÍ [ 'myvar' ] = 6 ; |
| @name | Jméno, štítek | |
| @staticvar | Popis statických proměnných | /** * @staticvar integer $staticvar * @return vrací celočíselnou hodnotu */ |
| @return | Popis návratové hodnoty | |
| @todo | Poznámky pro pozdější implementaci. | /** * DocBlock s vnořenými seznamy * @todo Jednoduchý seznam TODO * - položka 1 * - položka 2 * - položka 3 * @todo Vnořený seznam TODO * <ol> * <li>položka 1.0</li> * <li> položka 2.0</li> * <ol> * <li>položka 2.1</li> * <li>položka 2.2</li> * </ol> * <li>položka 3.0</li> * </ol> */ |
| @link | Odkaz | /** * Toto je příklad {@link http://www.example.com vloženého hypertextového odkazu} */ |
| @deprecated (@deprec) | Popis zastaralého bloku | /** * @deprecated description * @deprec je synonymum pro deprecated */ |
| @example | Příklad | /** * @abstrakt * @přístup veřejný nebo soukromý * @datum názvu autorských práv * @příklad /cesta/k/příkladu * @ignore * @interní soukromé informace pro specialisty * @typ parametru [$varname] popis vstupního parametru * @return typ návratové hodnoty popis * @viz další název prvku (odkaz) * @od verze nebo data * @statický */ |
| @see | Odkaz na jiné místo v dokumentaci | |
| Další deskriptory | ||
| @copyright • @license • @filesource • @category • @since • @abstract • @access • @example • @ignore • @internal • @static • @throws • @uses • @tutorial | ||
Příklad komentáře dokumentu pro funkci v programu Java , který má být použit Javadoc :
/** * Zkontroluje, zda je přesun platný. * Například pro nastavení tahu e2-e4 napište isValidMove(5,2,5,4); * @author John Doe * @param theFromFile Vertikální, kde je tvar (1=a, 8=h) * @param theFromRank Horizontální, kde je tvar (1...8) * @param theToFile Vertikální, kde je tvar je proveden pohyb (1=a, 8=h) * @param theToRank Horizontální poloha buňky, do které se má přesunout (1...8) * @return true, pokud je pohyb platný, a false, pokud není platný */ boolean is ValidMove ( int theFromFile , int theFromRank , int theToFile , int theToRank ) { . . . }Příklady pro různé jazyky a programovací prostředí: