Javadoc

Z Wikipedii, wolnej encyklopedii
Skocz do: nawigacja, szukaj

Definicja intuicyjna:

Javadoc (wym. "dżawadok") to 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 jego twórców.

Javadoc to generator dokumentacji stworzony przez firmę Sun Microsystems. Narzędzie to generuje dokumentację kodu źródłowego Javy na podstawie zamieszczonych w kodzie komentarzy Javadoc.

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

Struktura komentarza Javadoc[edytuj | edytuj kod]

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[edytuj | edytuj kod]

/**
 * 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[edytuj | edytuj kod]

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 kontaktem między implementującymi a korzystającymi z udokumentowanego API[1].

Przypisy

Linki zewnętrzne[edytuj | edytuj kod]