JavaDoc - kompletní průvodce tagy - Builder.cz - Informacni server o programovani

Navigace:  » Úvodní stránka  » Rubriky  » Java  

17. prosince 2001, 00.00 | Pokračování seriálu o JavaDocu. Dnes se budeme podrobně věnovat jednotlivým tagům, které se dají použít v JavaDocu, a to až do verze Javy 2 JDK/SDK 1.4.

Tento díl se bude zcela věnovat otázce tagů. Probereme si zde všechny dostupné tagy JDK/SDK až do verze 1.4. Ještě bych rád připomněl, že kompletní seznam všech tagů, a jejich dostupnost, tím myslím, od které verze Javy jsou dostupné, jsem uvedl na konci předchozího dílu.

{@ ... } (nestandardní)

tento nestandardní tag lze použít pro vložení komentáře, který je vidět jen ve vašem dokumentu. JavaDoc ho ignoruje, a tudíž není zapsán do výsledných HTML souborů.

/** text {@ můj komentář k textu } pokračování textu */

@author "text" "text2" ...

tag označuje jméno autora daných java souborů. Text označuje jména autora, dal jsem ho záměrně do uvozovek, protože jméno se obvykle skládá z jména a příjmení. A pokud byste to napsali bez uvozovek, JavaDoc by to přeložil jako dva autory a oddělil by je čárkou. Text2 a další samozřejmě nemusí být vůbec psaný pokud soubory vytvořil jeden člověk.

/* @author "Švec Petr" */

@deprecated text

tak o tomto tagu jsem se zde ještě nezmínil. Tak jako jsou v samotné Javě deprecated metody, tak i vaše soubory mohou obsahovat tyto metody. A proto zde máme tag, který jméno této metody přidá do souboru deprecatiovaných metod a současně v daném objektu označí metodu jako Depreciated.

/** @deprecated Tato metoda je nahrazena {@link #getKindOfCustomer} */

Bylo by vcelku dobré do popisu metody také přidat link na novou metodu, která ji nahradila.

{@docRoot}

ukazuje na relativní cestu - kořenový adresář dokumentace tj. místo kde jsou uloženy vygenerované dokumenty. Takže jestliže jste kdekoliv v adresářové struktuře, pak lze přes tento tag se odkázat na zcela přesné místo. Na příkladu ukáži jak se z jakéhokoliv dokumentu odkázat na dokument, který jsem uložil do kořenového adresáře dokumentace.

/** Podívejte se na informace <a href="{@docRoot}/about.html">o autorovi</a>. */

@exception třída popis

Nutno říci, že exception, Java 1.0, je synonymem k throws z Java 1.2. Více viz tedy throws.

@inheritDoc

tento tag provádí to, že vkládá do vašeho souboru dokumentaci, která je psaná v rodičovské třídě. Je to vcelku výhodné z pohledu rodič - dítě, kde množství věcí je stejné a díky tomuto tagu je nemusíte psát či kopírovat a jsou obsaženy v dokumentaci. Pozor dělá to jen tam kde máte v rodiči dokumentaci a v aktuálním souboru ne.

/** {inheritDoc} */ public static void myPrint(String[] args) /* zkopíruje dokumentaci z rodičovské třídy - musí ji obsahovat*/ { ... }

@link odkaz popisek

Již víme, že do odkazu linku se mohou umisťovat odkazy na metody, a že se zobrazí neodsazeně v řádce. Co jsem zde ještě nezmínil, je že lze nastavit i jeho popisek.

... viz. {@link #main(String[] args)} ... /* nebo s popiskem "metoda main" */ ... viz. {@link #main(String[] args) metoda main} ... /* stejného výsledku dosáhnete i se zápisem */ ... viz. {@link #main metoda main} ...

U metod obecně není nutné psát specifikaci parametrů a popisek, pokud metoda není přetížená, a tím se vcelku zjednodušit zápis.

@linkplain odkaz popisek

linkplain je absolutně stejná na funkci jako @link. Jediný rozdíl, v čem se oba tagy liší je to, že link vypisuje odkaz ve fontu pro kód, a linkplain vypisuje odkaz ve standardním fontu.

/** Doporučil bych si prostudovat {@linkplain main()}. */

@param parametr text

tento tag slouží k lepšímu popisu jednotlivých parametrů / proměnných předávaných metodě. V parametru specifikujete název proměnné, no a v textu již její bližší komentář.

/** tato metoda vykreslí na plátno booklet @param label tato proměná obsahuje název CD-ROMu @param items obsahuje jednotlivé položky obsažené na disku */ public static void doBookLet(String label, HashSet items) { ... }

@return text

text obsahuje komentář k tomu co vrací metoda.

/** metoda v podstatě pouze vloží obsah args do hashe @return výstupem je naplněný HashSet, pokud vstup obsahoval chybu, pak je výstup prázdný. */ public HashSet doList(String[] args) { ... }

@see URI popisek

see lze použít několika způsoby. Především pomocí něj, lze vytvářet odkazy inline - v řádce a block - ve vlastním odstavci "See Also".

/** inline odkaz: * Text ... {@see <a href="http://java.sun.com/">Java Sun</a>} ... * blokové odkaz (až za textem): @see java.lang.Object */

To že URI adresa nemusí být jen URL si můžeme ukázat na následujícím příkladu, který je krásně abstraktní. Říká kde to najdeme = URN, ale ne již jeho URL.

/* @see "The Java Programming Language" */

V rámci URI resp. v URL můžeme použít odkaz na zadaný pomocí HTML tagu a včetně parametru, či odkaz na proměnou či metodu ať z tohoto či jiného package. Bylo by dobré si vzpomenout na to, že pokud daná metody není přetížená tak ji mohu napsat zkráceně tj. bez vstupních parametrů.

/** @see countIt {@ odkaz v mé třídě (na metodu countIt(...) } @see Form2.create {@ odkaz mimo mou třídu (do souboru Form2.java) } @see java.applet.Applet {@ odkaz mimo můj package } */

Popisek je nepovinný atribut, pokud není vyplněn, použije se defaultní hodnota tj. URI. Požíváním popisků můžete výrazně přispět k čitelnosti dokumentu. Bude-li v dokumentu pár odkazů i s definicí parametrů, tak se zase tak moc neděje. Ale bude-li v "See Also" vypsáno pár metod i s parametry, tak se v tom skoro nevyznáte.

/** @see #doBookLet {@ výstup: doBookLet(java.lang.String, java.util.HashSet) } @see #doBookLet doBookLet {@ výstup: doBookLet } */

@since text

tento tagu je základem pro vytváření nových verzí, aktualizaci. Ukládají se do něj hodnoty od které verze je dané něco dostupné. V Javě tj. např. JDK1.2.

/* @since CDLabeler1.1 */

@serial text
 & @serialField name typ text
 & @serialData text

tyto tři tagy nejsou až tak moc obvyklé. Lépe řečeno, kdo nepůjde do Javy tvrdě, stěží je kdy použije. Mimo to není jejich použití tak přímočaré jako u ostatních. Spíše by to vydalo na samotných článek. Proto zájemce o toto téma odkazuji na zdroj zmíněný v závěru, kde najdou tolik informací, které by zde smysluplně nemohl naplácat.

@throws výjimka text

jak již bylo zmíněno throws je synonymem dříve používaného slova exception. V podstatě uvedením tohoto slova přidáváte do vygenerovaných odkazů k dané metodě nový odstavec, ve kterém jsou vámi uvedené výjimky, které zde "mohou nastat".

/* @throws IOException v případě, že selhalo uložení dat na zadaného souboru */

@version text

jak je zřejmé, do textu si můžete uložit verzi - měla by být stejná s verzí programu, pro kterou vytváříte dokumentaci. Taky by se mělo shodovat s tím co uvádíte do tagu since. Ale všeobecně není žádné pravidlo co přesně by mělo být uvedeno v tomto textu

/* @version CDLabeler1.2 */

A jako poslední, ani neuvedený v seznamu, tu máme nestandardní a nefunkční tag

@copyright text text... (nefunkční)

ač několikráte jsem se již setkal s tímto tagem uváděním na stejném místě jako autor, přesto jsem ho nenašel ve specifikaci. JavaDoc na něj nijak nereaguje. Používání tohoto tagu si vyplývá spíše z potřeby označovat si dobu vzniku dokumentu a "oznámit práva".

/** @copyright Svec Petr 2001 */

Kde se dají použít jednotlivé tagy

Vzhledem k tomu, že jsem zde uvedl dost nových tagů, o kterých jsem se v úvodu nezmínil. Tak se zde podrobně zaměřím na to kde mohu, které tagy používat.

Jak podle této tabulky zjistíte, v předchozím textu jsem uváděl nepřesnosti když jsem daný tag vztahoval např. jen k metodě a on může být i jinde. Dělal jsem to jen kvůli čitelnosti textu, s tím, že každý si jeho použití může rychleji najít v tabulce než v textu.

Výskyt / Tag

a u t h o r

d e p r e c a t e d

d o c R o o t

l i n k

p a r a m

r e t u r n

s e e

s e r i a l

s e r i a l D a t a

s e r i a l F i e l d

s i n c e

t h r o w s

v e r s i o n

Overview

Package

Třída/Interface

Proměnné apod.

Metody (+konstruktor)

Slovo závěrem. Příští díl bude o příkazové řádce JavaDocu. Přesněji řečeno je jednotlivých jejích parametrech.