Javadoc
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[1]. Umożliwiają one również wykorzystanie takiej dokumentacji jako pomoc dla programisty podczas pisania kodu.
Spis treści |
Struktura komentarza Javadoc [edytuj]
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]
/** * 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]
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[2].
