Java Language => Dokumentowanie kodu Java

Wprowadzenie

Dokumentacja kodu java jest często generowana przy użyciu javadoc . Javadoc został stworzony przez Sun Microsystems w celu generowania dokumentacji API w formacie HTML z kodu źródłowego Java. Korzystanie z formatu HTML zapewnia wygodę łączenia razem powiązanych dokumentów.

Składnia

/ ** - uruchomienie JavaDoc w klasie, polu, metodzie lub pakiecie
@author // Aby wymienić autora klasy, interfejsu lub wyliczenia. Jest wymagane.
@version // Wersja tej klasy, interfejsu lub wyliczenia. Jest wymagane. Możesz użyć makr, takich jak% I% lub% G%, dla swojego oprogramowania kontroli źródła do wypełnienia przy kasie.
@param // Aby wyświetlić argumenty (parametry) metody lub konstruktora. Podaj jeden tag @param dla każdego parametru.
@return // Aby wyświetlić typy zwracane dla metod nie void.
@exception // Pokazuje, jakie wyjątki mogą zostać wygenerowane przez metodę lub konstruktor. Wyjątki, które MUSZĄ zostać złapane, powinny zostać wymienione tutaj. Jeśli chcesz, możesz również dołączyć te, które nie muszą zostać złapane, takie jak ArrayIndexOutOfBoundsException. Określ jeden @ wyjątek dla każdego wyjątku, który może zostać zgłoszony.
@throws // To samo co @exception.
@ patrz // Linki do metody, pola, klasy lub pakietu. Użyj w postaci pakietu. Klasa # coś.
@since // Po dodaniu tej metody pole lub klasa. Na przykład JDK-8 dla klasy takiej jak java.util.Optional <T> .
@serial, @serialField, @serialData // Używany do wyświetlania serialVersionUID.
@deprecated // Aby oznaczyć klasę, metodę lub pole jako przestarzałe. Na przykład może to być java.io.StringBufferInputStream . Zobacz pełną listę istniejących przestarzałych klas tutaj .
{@link} // Podobne do @see, ale można go używać z niestandardowym tekstem: {@link #setDefaultCloseOperation (int closeOperation) patrz JFrame # setDefaultCloseOperation, aby uzyskać więcej informacji}.
{@linkplain} // Podobne do {@link}, ale bez czcionki kodowej.
{@code} // W przypadku kodu dosłownego, takiego jak tagi HTML. Na przykład: {@code <html> </html>}. Będzie to jednak używać czcionki o stałej szerokości. Aby uzyskać ten sam wynik bez czcionki Monospace, użyj {@literal}.
{@literal} // Taki sam jak {@code}, ale bez czcionki o stałej szerokości.
{@value} // Pokazuje wartość pola statycznego: wartość JFrame # EXIT_ON_CLOSE to {@value}. Lub możesz utworzyć link do określonego pola: Używa nazwy aplikacji {@value AppConstants # APP_NAME}.
{@docRoot} // Folder główny JavaDoc HTML względem bieżącego pliku. Przykład: <a href="{@docRoot}/credits.html"> Kredyty </a>.
HTML jest dozwolony: <code> „Hi cookies” .substring (3) </code>.
* / - koniec deklaracji JavaDoc

Uwagi

Javadoc to narzędzie zawarte w JDK, które umożliwia konwersję komentarzy w kodzie do dokumentacji HTML. Specyfikacja API Java została wygenerowana przy użyciu Javadoc. To samo dotyczy większości dokumentacji bibliotek stron trzecich.

Dokumentacja klasowa

Wszystkie komentarze Javadoc zaczynają się od komentarza blokowego, po którym następuje gwiazdka ( /** ) i kończą się, gdy komentarz blokowy ( */ ). Opcjonalnie każda linia może zaczynać się od dowolnej białej spacji i pojedynczej gwiazdki; są one ignorowane podczas generowania plików dokumentacji.

/**
 * Brief summary of this class, ending with a period.
 *
 * It is common to leave a blank line between the summary and further details.
 * The summary (everything before the first period) is used in the class or package 
 * overview section.
 *
 * The following inline tags can be used (not an exhaustive list): 
 * {@link some.other.class.Documentation} for linking to other docs or symbols
 * {@link some.other.class.Documentation Some Display Name} the link's appearance can be 
 * customized by adding a display name after the doc or symbol locator
 * {@code code goes here} for formatting as code
 * {@literal <>[]()foo} for interpreting literal text without converting to HTML markup 
 * or other tags.
 *
 * Optionally, the following tags may be used at the end of class documentation 
 * (not an exhaustive list):
 *
 * @author John Doe
 * @version 1.0
 * @since 5/10/15
 * @see some.other.class.Documentation
 * @deprecated This class has been replaced by some.other.package.BetterFileReader
 * 
 * You can also have custom tags for displaying additional information.
 * Using the @custom.<NAME> tag and the -tag custom.<NAME>:htmltag:"context"
 * command line option, you can create a custom tag.
 *
 * Example custom tag and generation:
 * @custom.updated 2.0    
 * Javadoc flag: -tag custom.updated:a:"Updated in version:"
 * The above flag will display the value of @custom.updated under "Updated in version:"
 *
 */
public class FileReader {
}

Te same znaczniki i format, które są używane w Classes mogą być również używane w Enums i Interfaces .

Dokumentacja metody

/**
 * Brief summary of method, ending with a period.
 *
 * Further description of method and what it does, including as much detail as is 
 * appropriate.  Inline tags such as
 * {@code code here}, {@link some.other.Docs}, and {@literal text here} can be used.
 *
 * If a method overrides a superclass method, {@inheritDoc} can be used to copy the 
 * documentation
 * from the superclass method
 *
 * @param stream Describe this parameter.  Include as much detail as is appropriate
 *               Parameter docs are commonly aligned as here, but this is optional.
 *               As with other docs, the documentation before the first period is 
 *               used as a summary.
 *
 * @return Describe the return values.  Include as much detail as is appropriate
 *         Return type docs are commonly aligned as here, but this is optional.
 *         As with other docs, the documentation before the first period is used as a 
 *         summary.
 *
 * @throws IOException Describe when and why this exception can be thrown.
 *                     Exception docs are commonly aligned as here, but this is 
 *                     optional.
 *                     As with other docs, the documentation before the first period 
 *                     is used as a summary.
 *                     Instead of @throws, @exception can also be used.
 *
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated  Describe why this method is outdated. A replacement can also be specified.
 */
public String[] read(InputStream stream) throws IOException {
    return null;
}

Dokumentacja terenowa

/**
 * Fields can be documented as well.
 * 
 * As with other javadocs, the documentation before the first period is used as a
 * summary, and is usually separated from the rest of the documentation by a blank 
 * line.
 * 
 * Documentation for fields can use inline tags, such as:
 * {@code code here}
 * {@literal text here}
 * {@link other.docs.Here}
 * 
 * Field documentation can also make use of the following tags:
 * 
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated Describe why this field is outdated
 */
public static final String CONSTANT_STRING = "foo";

Dokumentacja paczki

Java SE 5

Możliwe jest tworzenie dokumentacji na poziomie pakietu w Javadocs za pomocą pliku o nazwie package-info.java . Ten plik musi być sformatowany jak poniżej. Wiodące białe znaki i gwiazdki są opcjonalne, zwykle występują w każdej linii ze względu na formatowanie

/**
 * Package documentation goes here; any documentation before the first period will 
 * be used as a summary.
 *
 * It is common practice to leave a blank line between the summary and the rest
 * of the documentation; use this space to describe the package in as much detail
 * as is appropriate.
 * 
 * Inline tags such as {@code code here}, {@link reference.to.other.Documentation},
 * and {@literal text here} can be used in this documentation.
 */
package com.example.foo;

// The rest of the file must be empty.

W powyższym przypadku należy umieścić ten plik package-info.java w folderze pakietu Java com.example.foo .

Spinki do mankietów

Łączenie z innymi Javadocs odbywa się za @link tagu @link :

/**
 * You can link to the javadoc of an already imported class using {@link ClassName}.
 *
 * You can also use the fully-qualified name, if the class is not already imported: 
 *  {@link some.other.ClassName}
 *
 * You can link to members (fields or methods) of a class like so:
 *  {@link ClassName#someMethod()}
 *  {@link ClassName#someMethodWithParameters(int, String)}
 *  {@link ClassName#someField}
 *  {@link #someMethodInThisClass()} - used to link to members in the current class
 *  
 * You can add a label to a linked javadoc like so:
 *  {@link ClassName#someMethod() link text} 
 */

Za pomocą znacznika @see możesz dodawać elementy do sekcji Zobacz także . Podobnie jak @param lub @param @return miejsce, w którym się pojawiają, nie ma znaczenia. Specyfikacja mówi, że powinieneś napisać to po @return .

/**
 * This method has a nice explanation but you might found further
 * information at the bottom.
 *
 * @see ClassName#someMethod()
 */

Jeśli chcesz dodać linki do zasobów zewnętrznych , możesz po prostu użyć znacznika HTML <a> . Możesz używać go bezpośrednio w dowolnym miejscu lub wewnątrz tagów @link i @see .

/**
 * Wondering how this works? You might want
 * to check this <a href="http://stackoverflow.com/">great service</a>.
 *
 * @see <a href="http://stackoverflow.com/">Stack Overflow</a>
 */

Budowanie Javadocs z wiersza poleceń

Wiele IDE zapewnia obsługę automatycznego generowania HTML z Javadocs; niektóre narzędzia do budowania (na przykład Maven i Gradle ) mają również wtyczki, które mogą obsługiwać tworzenie HTML.

Te narzędzia nie są jednak wymagane do generowania Javadoc HTML; można to zrobić za pomocą narzędzia javadoc wiersza poleceń.

Najbardziej podstawowym zastosowaniem tego narzędzia jest:

javadoc JavaFile.java

Który wygeneruje HTML z komentarzy Javadoc w JavaFile.java .

Bardziej praktyczne użycie narzędzia wiersza poleceń, które rekurencyjnie odczyta wszystkie pliki Java w [source-directory] , utworzy dokumentację dla [package.name] paczki i wszystkich podpakietów oraz umieści wygenerowany kod HTML w [docs-directory] jest:

javadoc -d [docs-directory] -subpackages -sourcepath [source-directory] [package.name]

Dokumentacja kodu wbudowanego

Poza kodem dokumentacji Javadoc można dokumentować w trybie on-line.

Komentarze jednowierszowe są rozpoczynane przez // i mogą być umieszczone po instrukcji w tym samym wierszu, ale nie wcześniej.

public void method() {
  
  //single line comment
  someMethodCall(); //single line comment after statement
  
}

Komentarze wieloliniowe są zdefiniowane pomiędzy /* i */ . Mogą obejmować wiele wierszy, a nawet mogą znajdować się między instrukcjami.

public void method(Object object) {
  
  /*
    multi 
    line 
    comment
  */
  object/*inner-line-comment*/.method(); 
}

JavaDocs to specjalna forma wieloliniowych komentarzy, zaczynających się od /** .

Ponieważ zbyt wiele wbudowanych komentarzy może zmniejszać czytelność kodu, należy ich używać rzadko, na wypadek, gdyby kod nie był wystarczająco zrozumiały lub decyzja projektowa nie była oczywista.

Dodatkowym przypadkiem użycia komentarzy jednowierszowych jest użycie TAG, które są krótkimi słowami kluczowymi opartymi na konwencji. Niektóre środowiska programistyczne uznają pewne konwencje dotyczące takich pojedynczych komentarzy. Typowe przykłady to

//TODO
//FIXME

Lub wydawaj referencje, np. Dla Jiry

//PRJ-1234

Fragmenty kodu w dokumentacji

Kanonicznym sposobem pisania kodu w dokumentacji jest konstrukcja {@code } . Jeśli masz wielowierszowe zawijanie kodu w <pre></pre> .

/**
 * The Class TestUtils.
 * <p>
 * This is an {@code inline("code example")}.
 * <p>
 * You should wrap it in pre tags when writing multiline code.
 * <pre>{@code
 *  Example example1 = new FirstLineExample();
 *  example1.butYouCanHaveMoreThanOneLine();
 * }</pre>
 * <p>
 * Thanks for reading.
 */
class TestUtils {

Czasami może być konieczne wstawienie złożonego kodu w komentarzu javadoc. Znak @ jest szczególnie problematyczny. Zastosowanie starego <code> obok konstrukcji {@literal } rozwiązuje problem.

/**
 * Usage:
 * <pre><code>
 * class SomethingTest {
 * {@literal @}Rule
 *  public SingleTestRule singleTestRule = new SingleTestRule("test1");
 *
 * {@literal @}Test
 *  public void test1() {
 *      // only this test will be executed
 *  }
 *
 *  ...
 * }
 * </code></pre>
 */
class SingleTestRule implements TestRule { }

Modified text is an extract of the original Stack Overflow Documentation

Licencjonowany na podstawie CC BY-SA 3.0

Nie związany z Stack Overflow

Java Language
Dokumentowanie kodu Java

Szukaj…