JavaDoc - kompletní průvodce tagy - 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 - kompletní průvodce tagy

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

ne

ano

ano

ano

ne

ne

ano

ne

ne

ne

ano

ne

ne

Package

ne

ano

ano

ano

ne

ne

ano

ne

ne

ne

ano

ne

ne

Třída/Interface

ano

ano

ano

ano

ne

ne

ano

ne

ne

ne

ano

ne

ano

Proměnné apod.

ne

ano

ano

ano

ne

ne

ano

ano

ne

ano

ano

ne

ne

Metody (+konstruktor)

ne

ano

ano

ano

ano

ano

ano

ne

ano

ne

ano

ano

ne

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.

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: