Javadoc

Technology

12 hours ago

Author

javadoc je softwarová pomůcka (utilita) firmy Sun Microsystems™ pro automatické generování dokumentace k programu. Jedná se o co do velikosti malou konzolovou aplikaci, která umí procházet zdrojový kód programů v jazyku Java™, vyhledávat speciálně uvozené komentáře a ty posílat na výstup současně generovaného HTML souboru. Pro některé softwarového vývojáře je představa, že po dokončení určité verze svého projektu, budou muset ještě trávit několik hodin vypracováváním dokumentace, nepříjemná - musí totiž znovu procházet veškeré zdrojové kódy, popisovat každou funkci, konstantu nebo třídu, snažit se o jednotný vzhled, atd. Pokud používají javadoc a dodržují alespoň základní komentování ve svých zdrojových kódech, mohou přímo z nich dokumentaci vygenerovat okamžitě bez jakékoli práce navíc.

Javadoc podporuje generovat dokumentaci v HTML rámcích i bez nich, jeho poslední verze podporují kaskádové styly. Při jakékoli změně ve zdrojových kódech je možno dokumentaci znovu vygenerovat bez obtížného hledání a zjišťování změn a úpravě v dokumentaci. +more Výsledné výstupy javadocu jsou poměrně přehledné a většinou své účely postačují. Javadoc umí poznat, který komentář má do dokumentace zahrnout, stejně jako umí identifikovat syntaktický prvek jazyka, k němuž má komentář, který mu předchází, připojit.

Komentáře jsou v jazyku Java stejné jako v jazyku C++. Víceřádkové komentáře, které má javadoc identifikovat, začínají znaky /** a končí znaky */. +more Kromě toho je možno javadocu předávat informace pomocí rezervovaných slov, začínající znakem @.

Javadoc je často součástí integrovaného prostředí, které jej umí spouštět (vybráním z roletového menu). Javadoc má mnoho přepínačů, pomocí nichž je možno nakonfigurovat si jeho výstup.

Příklad

/** * Validates a chess move. Use {@link #doMove(int, int, int, int)} to move a piece. +more * * @param theFromFile file from which a piece is being moved * @param theFromRank rank from which a piece is being moved * @param theToFile file to which a piece is being moved * @param theToRank rank to which a piece is being moved * @return true if the chess move is valid, otherwise false */ boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) { … }.

/** * Move a chess piece. * * @see java.math.RoundingMode */ boolean doMove(int theFromFile, int theFromRank, int theToFile, int theToRank) { … }