JavaDoc - lehký úvod - Builder.cz - Informacni server o programovani

java

java

11. prosince 2001, 00.00 | Pracujete v oboru? Pak jistě víte, že jedna z důležitých činností je vytváření dokumentace. A právě vytvářením dokumentace v Javě se zde budeme podrobně věnovat.

JavaDoc je nástroj, který umožňuje vytvářet programátorskou dokumentaci k vašim projektům ve stejném stylu jako je samotná dokumentace k Javě. Z toho plyne, že samotné vytváření takové dokumentace se musí provádět přes standardní nástroj k tomu určený, v našem případě JavaDoc. Takovýto nástroj má více méně pevnou syntaxi. A právě na tu se zde podíváme.

Samotný zápis instrukcí pro JavaDoc, které se mají zpracovat se provádí do speciálního komentáře začínající ho /** a uzavřeného */. Kam se umisťuje? Tento zápis se umisťuje před deklaraci třídy, metody či proměnné aj.

Poznámka: tento zápis nemá žádný vliv na vaše komentáře.

Poznámka: instrukce pro JavaDoc umístěné před klausulí import jsou ignorovány.
Poznámka #2: vygenerovaný soubor bude obsahovat stejný komentář pro obě proměnné count. Pokud by jste potřebovali komentáře jiné či pro jednu z nich vůbec, musíte rozdělit deklaraci na dvě.

Předpokladem pro spuštění JavaDocu je mít nastavenou cestu do adresáře BIN, kde máte nainstalovanou Javu. Lze to udělat např. takto

Ta nejzákladnější možnost jak spustit JavaDoc je spustit ho s parametrem souboru, pro který chceme vytvořit dokumentaci. Vzhledem k tomu, že do vytvořené dokumentace se vždy zahrnují jen soubory, které byli zadány, a projekt se obvykle skládá z více souborů, není to zrovna ideální řešení. Je praktičtější spustit JavaDoc se selekcí souborů pro zpracování.

Oba dva příkazy vytvoří následující soubory:

Detailně se budeme věnovat příkazové řádce JavaDocu ve třetím dílů tohoto seriálu.

Především je to text začínající *. Samotný text je pak interpretován jako HTML syntaxe, takže můžete používat HTML tagy. Pozor, ale na to, abyste tím nedostali moc daleko od standardního vzhledu. Obzvláště pak při používání nadpisů či nějakých dekorací - myslete na to, že tako dokumentace nejsou omalovánky pro normálního uživatele, ale spíše prostý text pro programátora.

Použitím HTML tagu pre si pak můžete zjednodušit práci v tom, že nemusíte psát tagy pro ukončení řádky či zaměňovat více mezer za  . Ovšem má to i negativní vliv tom, že řádky se nezalomují, a tudíž se dokument může stát obtížně čitelným.

V samotném tagu textu, po hvězdičce, můžete zapisovat svoje vlastní komentáře, které se nijak nepromítnou do vygenerovaných souborů. Takovýto komentář v dokumentaci se zapisuje mezi {@ a }. Vypadá to zhruba takto:

Další velmi používaný tagem je odkaz na jinou třídu ("See Also"). Například závisí-li vaše třída na jiné či má nějaké potomky, pak pomocí tagu @see jmeno vygenerujete odkaz. Pro odkaz mimo dokumentaci, lze využít HTML tagu a a to několika možnostmi.

Předešlý příkaz vytváří související odkazy s dokumentací na konci popisu, ale při psaní dokumentace se může hodit vložení odkazu inline, ne do nového odstavce (tak jako to dělá HTML tag a). Toho můžeme dosáhnout použitím tagu @link odkaz.

Možná jste si všimli, že již v předchozím příkladu jsem používal závorky {, }. Ty mají funkci begin - end, pro odlišení kde začíná tag a kde končí. Tento tag se pak tedy může zapisovat ve tvaru {@link text}.

JavaDoc nahradí link main(java.lang.String[] args).

Nyní asi tak víme, jak zapisovat tagy a jaké tak zhruba mají možnosti, podívejme se tedy na jejich úplný seznam. Pro lepší představivost v druhém sloupečku uvádím, od které verze JDK/SDK je daný tag dostupný. U některých tagů jsou pak dvě verze, což značí to, že funkce či zápis daného tagu byl přepracován.

Co na závěr? V příštím díle se podíváme detailně na jednotlivé tagy uvedené v předešlém seznamu. Lze říci, že tento seznam je obsahem příštího dílu.