Javadoc

Javadoc – narzędzie automatycznie generujące dokumentację na podstawie zamieszczonych w kodzie źródłowym znaczników w komentarzach. Javadoc został stworzony specjalnie na potrzeby języka programowania Java przez firmę Sun Microsystems.

Wiele nowoczesnych IDE wspomaga tworzenie dokumentacji i pozwala na automatyczne jej generowanie. Umożliwiają one również wykorzystanie takiej dokumentacji jako pomoc dla programisty podczas pisania kodu.

Struktura komentarza Javadoc

Komentarz Javadoc oddzielony jest znacznikami /** i */, które sprawiają, że ich zawartość (czyli to, co znajduje się między nimi), jest ignorowana przez kompilator. Pierwsza jego linia to opis metody lub klasy, która zadeklarowana jest poniżej. Dalej znajduje się pewna liczba opcjonalnych tagów, które z kolei opisują parametry metody (@param), wartość zwracaną (@return) itp.

Przykład

/**
 * 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)
{
    ... 
}

Pisanie dokumentacji

Pisanie dokumentacji w kodzie zostało ustandaryzowane, co oznacza, że istnieją szczegółowe konwencje, których należy przestrzegać, jako że taka dokumentacja jest niejako kontraktem między implementującymi a korzystającymi z udokumentowanego API.

Linki zewnętrzne

• Strona narzędzia Javadoc (ang.)
• Jak pisać Javadoc (ang.)