Javadoc

Z Multimediaexpo.cz

Verze z 29. 10. 2011, 14:04

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á - musejí 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. 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 */. 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.
 * 
 * @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)
{
    ... 
}

Související články

• Doxygen