Generátor dokumentace

Generátor dokumentace je softwarová utilita (spadající do skupiny CASE nástrojů), schopná (pomocí syntaktické analýzy) parsovat zdrojový kód, extrahovat z jeho komentářů informace určené pro dokumentaci a tyto informace poté zobrazit nebo zformátovat a poslat na výstup ve zvolené formě.

Generátor dokumentace začíná syntaktickou analýzou hlavního zdrojového souboru. Při analýze si všímá komentářů – pokud je komentář navíc uvozen dohodnutou sekvencí znaků, začlení jeho obsah mezi dokumentaci, jež bude záhy generovat. Detekuje též příkazy/direktivy vkládání (inkludování) pomocných souborů, které zahrne k souborům, jež má projít. Většina lepších generátorů dokumentace umí vysledovat kontext aktuálního komentáře, popřípadě co jej bezprostředně předchází nebo následuje.

Výsledné získané informace mají charakter hierarchicky strukturovaných článků – každý článek týkající se jednoho syntaktického prvku v daném projektu. Mezi výstupními formáty, který tento typ obsahu umí efektivně pojmout, tedy většinou nechybí formáty DocBook, vícestránkové HTML, soubory nápovědy v systému Windows (.hlp, .chm) a Unix (tzv. „man pages“) a mnohé další.

Výhodou takto generované dokumentace je neoddělitelnost a konzistentnost dokumentace a kódu ve své zdrojové podobě, a z toho vyplývající možnost pohodlně dokumentovat zdrojový kód bez nutnosti neustále přepínat mezi IDE prostředím a externím textovým editorem a případě větších změn ve zdrojovém souboru tyto změny dodatečně a pracně vyhledávat a postihovat v dokumentaci a snažit se ji synchronizovat s aktuálním stavem zdrojového kódu.

Pravděpodobně nejpoužívanější formát dokumentace je Javadoc, který využívá víceřádkové komentáře (ohraničené sekvencí znaků /** ... */). Příkladem generátoru dokumentace v tomto formátu je nástroj Doxygen.

Externí odkazy

• en:Comparison of documentation generators - srovnání několika desítek existujících generátorů dokumentace