Javadoc - Javadoc

Zrzut ekranu

Javadoc (pierwotnie w postaci JavaDoc ) to generator dokumentacji stworzony przez Sun Microsystems dla języka Java (obecnie należący do Oracle Corporation ) do generowania dokumentacji API w formacie HTML z kodu źródłowego Java . Format HTML służy do dodania wygody polegającej na możliwości łączenia razem hiperłączy do powiązanych dokumentów.

Format „komentarzy do dokumentów” używany przez Javadoc jest de facto standardem branżowym do dokumentowania klas Java. Niektóre środowiska IDE , takie jak IntelliJ IDEA , NetBeans i Eclipse , automatycznie generują Javadoc HTML. Wiele edytorów plików pomaga użytkownikowi w tworzeniu źródła Javadoc i wykorzystuje informacje Javadoc jako wewnętrzne odniesienia dla programisty.

Javadoc udostępnia również API do tworzenia docletów i tagletów, które pozwala użytkownikom analizować strukturę aplikacji Java. W ten sposób JDiff może generować raporty o tym, co zmieniło się między dwiema wersjami API.

Javadoc nie wpływa na wydajność w Javie, ponieważ wszystkie komentarze są usuwane w czasie kompilacji. Pisanie komentarzy i Javadoc służy lepszemu zrozumieniu kodu, a tym samym lepszemu utrzymaniu go.

Historia

Javadoc był wczesnym generatorem dokumentacji języka Java . Przed użyciem generatorów dokumentacji zwyczajem było wykorzystywanie pisarzy technicznych, którzy zwykle pisali tylko samodzielną dokumentację oprogramowania, ale znacznie trudniej było zsynchronizować tę dokumentację z samym oprogramowaniem.

Javadoc był używany przez Javę od pierwszego wydania i jest zwykle aktualizowany przy każdej nowej wersji Java Development Kit .

@field Składnia Javadoc została naśladowane przez systemy dokumentacji dla innych języków, w tym przekroju języku Doxygena , w JSDoc systemu JavaScript i Apple HeaderDoc .

Architektura techniczna

Struktura komentarza Javadoc

Komentarz Javadoc jest oddzielony od kodu przez standardowe wielowierszowe znaczniki komentarza /* i */ . Tag otwierający (nazywany ogranicznikiem początku komentarza) ma dodatkową gwiazdkę, jak w /** .

1. Pierwszy akapit zawiera opis udokumentowanej metody.
2. Po opisie znajduje się różna liczba tagów opisowych, oznaczających:
   1. Parametry metody ( @param )
   2. Co zwraca metoda ( @return )
   3. Wszelkie wyjątki, które metoda może rzucić ( @throws )
   4. Inne mniej popularne tagi, np. @see (Tag „zobacz też”)

Omówienie Javadoc

Podstawową strukturą pisania komentarzy do dokumentów jest osadzenie ich wewnątrz /** ... */ . Blok komentarzy Javadoc jest umieszczony bezpośrednio nad elementami bez oddzielającego znaku nowej linii. Należy zauważyć, że wszystkie instrukcje importu muszą poprzedzać deklarację klasy. Deklaracja klasy zwykle zawiera:

// import statements

/**
 * @author      Firstname Lastname <address @ example.com>
 * @version     1.6                 (current version number of program)
 * @since       1.2          (the version of the package this class was first added to)
 */
public class Test {
    // class body
}

W przypadku metod istnieje (1) krótki, zwięzły, jednowierszowy opis wyjaśniający, do czego służy dana pozycja. Następnie (2) dłuższy opis, który może obejmować wiele akapitów. Szczegóły można w pełni wyjaśnić tutaj. Ta sekcja jest opcjonalna. Na koniec istnieje (3) sekcja tagów, która zawiera listę akceptowanych argumentów wejściowych i zwracanych wartości metody. Zauważ, że cały plik Javadoc jest traktowany jako HTML, więc sekcje z wieloma akapitami są oddzielone <p> znacznikiem „ ” podziału akapitu.

/**
 * Short one line description.                           (1)
 * <p>
 * Longer description. If there were any, it would be    (2)
 * here.
 * <p>
 * And even more explanations to follow in consecutive
 * paragraphs separated by HTML paragraph breaks.
 *
 * @param  variable Description text text text.          (3)
 * @return Description text text text.
 */
public int methodName (...) {
    // method body with a return statement
}

Zmienne są dokumentowane podobnie jak metody z tym wyjątkiem, że część (3) jest pomijana. Tutaj zmienna zawiera tylko krótki opis:

/**
 * Description of the variable here.
 */
private int debug = 0;

Należy zauważyć, że nie zaleca się definiowania wielu zmiennych w jednym komentarzu do dokumentacji. Dzieje się tak, ponieważ Javadoc odczytuje każdą zmienną i umieszcza je osobno na wygenerowanej stronie HTML z tym samym komentarzem do dokumentacji, który jest kopiowany dla wszystkich pól.

/**
 * The horizontal and vertical distances of point (x,y)
 */
public int x, y;      // AVOID

Zamiast tego zaleca się osobne zapisywanie i dokumentowanie każdej zmiennej:

/**
 * The horizontal distance of point.
 */
public int x;

/**
 * The vertical distance of point.
 */
public int y;

Tabela tagów Javadoc

W poniższej tabeli wymieniono niektóre z dostępnych tagów Javadoc:

Przykłady

Poniżej przedstawiono przykład Javadoc do udokumentowania metody. Zwróć uwagę, że odstępy i liczba znaków w tym przykładzie są zgodne ze stanem konwencji.

/**
 * Validates a chess move.
 *
 * <p>Use {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} to move a piece.
 *
 * @param fromFile file from which a piece is being moved
 * @param fromRank rank from which a piece is being moved
 * @param toFile   file to which a piece is being moved
 * @param toRank   rank to which a piece is being moved
 * @return            true if the move is valid, otherwise false
 * @since             1.0
 */
boolean isValidMove(int fromFile, int fromRank, int toFile, int toRank) {
    // ...body
}

/**
 * Moves a chess piece.
 *
 * @see java.math.RoundingMode
 */
void doMove(int fromFile, int fromRank, int toFile, int toRank)  {
    // ...body
}

Zobacz też

• Porównanie generatorów dokumentacji
• Komentarze do dokumentacji XML .NET

Bibliografia

Linki zewnętrzne

• Platforma Java, przewodnik Javadoc w wersji Standard Edition
• JSR 260 Javadoc Tag Technology Update Java Specification Request (definiuje nowe tagi Javadoc)
• Popraw na Javadoc dzięki Ashkelon
• Globaldocs: przeglądarka umożliwiająca jednoczesne przeglądanie wielu Javadoców.
• Różne dokumenty Java przekonwertowane do formatu Pomocy Windows