JavaDoc

Z FI WIKI
Přejít na: navigace, hledání

Javadoc je systém strukturovaných komentářů ve zdrojových kódech v Javě, z kterého (ve spolupráci s analýzou samotného zdrojového kódu) dokáže generátor (utilita javadoc, součást distribuce Javy) vygenerovat dokumentaci vašich tříd/balíčků, včetně rejstříku, vyhledávání apod.

  • Tutoriál k psaní dokumentace na sun.com
  • Javadoc-komentář se od normálního víceřádkového komentáře liší úvodní značkou (má hvězdičku navíc): /** */. Neexistuje speciální jednořádková verze ( jako /* */ versus //) - v tom případě prostě začnete komentář na stejném řádku jako skončíte :).
  • Javadoc-komentář je přidělen k nejbližší další deklaraci nějakého objektu ve zdrojovém kódu (tedy dokumentaci ke svým metodám, atributům, třídám pište těsně před ně).
  • Základní popis metody/třídy/atributu se píše jako samotný obsah komentáře. Není tedy nutné uvozovat je např. neexistujícím tagem @method...
  • V Javadoc-komentářích je možné používat HTML. Samotná dokumentace je totiž generována do HTML. Tak je možno přidat do ní odkazy na autory, popsat přehledněji použití metod třídy apod.
  • Pro strukturovanější popis entity je v javadoc definováno několik standardních tagů (při více parametrech, autorech apod. každý z nich dostane vlastní definici):
    • @param - popis parametrů - u tříd, rozhraní, metod, konstruktorů.
    • @return - umožňuje popsat návratovou hodnotu (jen u metod)
    • @throws (@exception - starší varianta) - umožňuje popsat, jakou výjimku metoda vrací
    • @author - povinné, pro třídy a rozhraní; jejich autor
    • @version - povinné, pro třídy a rozhraní; jejich verze
    • @see - umožňuje definovat odkazy jak jinam do metody (pomocí deklarace balicek.trida#clen_tridy nazev_odkazu) nebo na web (<a href="URL">odkaz<a>). Podrobněji viz zde.
    • @since - pro popis od které verze Javy je možno používat
    • @serial (nebo @serialField, @serialData) použivá se při serializování objektů (viz zde
    • @deprecated - pro popis, že se nemá metoda používat (většinou byla nahrazena novější variantou s jiným voláním)

Příklady použití:

@param [jméno parametru z deklarace] [jeho popis]
@return [popis návratové hodnoty]
@throws [typ výjimky - tj. jméno její třídy] [popis stavu způsobujícího výjimku]
@author [popis autora]
@version [popis verze]