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

Odběr fotomagazínu

Fotografický magazín "iZIN IDIF" každý týden ve Vašem e-mailu.
Co nového ve světě fotografie!

 

Zadejte Vaši e-mailovou adresu:

Kamarád fotí rád?

Přihlas ho k odběru fotomagazínu!

 

Zadejte e-mailovou adresu kamaráda:



Java

JavaDoc - lehký úvod

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.

/* můj vlastní komentář nemá žádný vliv na dokumentaci */

import java.util.*;
/* opět, můj vlastní komentář nemá žádný vliv na dokumentaci */

/** dokumentace třídy */
public class MyProg
{
     /** dokumentace k proměnné */
     public static int count, count2 = 10;

     /** dokumentace k metodě */
     public static void main(String[] args)
     {
     ...
     }
}

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ě.

Jak vygeneruji dokumentaci?

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

rem cestu si samozřejmě upravte
set PATH=C:\JDK1.4\BIN;%PATH%

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í.

rem spuštění JavaDocu pro jeden
javadoc myfile.java

rem spuštění JavaDocu pro všechny soubory Java v adresáři
javadoc *.java

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

allclasses-frame.html- seznam všech tříd všech balíků (je to levý frame)
allclasses-noframe.html- obdoba předchozího, pro prohlížeč, které nepodporuje framy
deprecated-list.html- seznam deprecated API všech balíků
help-doc.html- help pro uživatele, popis obecné hierachie
index.html- výchozí stránka dokumentace
index-all.html- defaultní index všeho (tříd, metod...)
overview-tree.html- hierarchie tříd všech balíků
package-list- seznam jmen jednotlivých balíků
serialized-form.html- seznam serialized ve všech balících
stylesheet.css- CSS (definice fontů a barev...) pro dokumentaci
[soubory tříd]- dokumenty pro jednotlivé třídy

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

Co může obsahovat?

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.

/*
 * Zde je můj popis dané třídy případně metody.
 * Dávejte si pozor na kódování češtiny nebo pište anglicky!
 * Opět text zpracovaný <b>JavaDoc</b>
 * Celý text je HTML, mohu používat formáty písem, či odkazy <a href="http://java.sun.com/">Java</a> či vypisovat bílé znaky jako &lt; &gt; &amp; aj.
 */

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 &nbsp;. Ovšem má to i negativní vliv tom, že řádky se nezalomují, a tudíž se dokument může stát obtížně čitelným.

/**<pre> Zde je můj popis dané třídy případně metody.
Dávejte si pozor na kódování češtiny!
Opět text zpracovaný <b>JavaDoc</b>
Celý text je HTML, mohu používat formáty písem, či odkazy <a href="http://java.sun.com/">Java</a> či vypisovat bílé znaky jako &lt; &gt; &amp; aj.</pre>
*/

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:

/** tady je nějaký text {@ toto nikdy neuvidíš} tady pokračuje nějaký text
*/

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.

/** inline odkazy:
 * Text... odkaz {@see <a href="http://java.sun.com/">Java Sun</a>} či přímo <a href="http://java.sun.com/">Java Sun</a> ... konec textu.
 * blokové odkazy (až za textem)
 @see nejaka_moje_trida
 @see java.lang.Object
 */

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.

/**
 * Více informací, zde jistě najdete v popisu metody {@link #main}
 * Pokud by jste nepoužili begin - end pak tag link by byl interpretován jako prostý text
 */

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.

Tag

Verze Javy

{@ ...}

nestandardní

@author

1.0

@deprecated

1.0

{@docRoot}

1.3

@exception

1.0

@inheritDoc

1.4

{@link}

1.2

{@linkplain}

1.4

@param

1.0

@return

1.0

@see

1.0

@serial

1.2, 1.4

@serialData

1.2

@serialField

1.2

@since

1.1

@throws

1.2

@version

1.0

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.

Obsah seriálu (více o seriálu):

Tématické zařazení:

 » Rubriky  » Java  

 

 

 

Nejčtenější články
Nejlépe hodnocené články

 

Přihlášení k mému účtu

Uživatelské jméno:

Heslo: