Java Language => Dokumentera Java-kod

Introduktion

Dokumentation för java-kod genereras ofta med javadoc . Javadoc skapades av Sun Microsystems i syfte att generera API-dokumentation i HTML-format från java-källkod. Att använda HTML-formatet ger bekvämligheten av att kunna länka relaterade dokument tillsammans.

Syntax

/ ** - start av JavaDoc i en klass, fält, metod eller paket
@author // För att namnge författaren till klassen, gränssnittet eller enum. Det är ett krav.
@version // Versionen av den klassen, gränssnittet eller enum. Det är ett krav. Du kan använda makron som% I% eller% G% för din källkontrollprogramvara för att fylla i kassan.
@param // Visa argumenten (parametrarna) för en metod eller en konstruktör. Ange en @param-tagg för varje parameter.
@ return // För att visa returtyperna för icke-ogiltiga metoder.
@ undantag // Visar vilka undantag som kan kastas från metoden eller konstruktören. Undantag som MÅSTE fångas bör listas här. Om du vill kan du också inkludera de som inte behöver fångas, som ArrayIndexOutOfBoundsException. Ange ett @exception för varje undantag som kan kastas.
@ kastar // Samma som @ exception.
@see // Länkar till en metod, fält, klass eller paket. Använd i form av paket. Klass # något.
@since // När den här metoden, fält eller klass lades till. Till exempel JDK-8 för en klass som java.util.Optional <T> .
@serial, @serialField, @serialData // Används för att visa serialVersionUID.
@deprecated // För att markera en klass, metod eller fält som avskrivna. Till exempel skulle man vara java.io.StringBufferInputStream . Se en fullständig lista över befintliga avskrivna klasser här .
{@link} // Liknar @see, men kan användas med anpassad text: {@link #setDefaultCloseOperation (int closeOperation) se JFrame # setDefaultCloseOperation för mer info}.
{@linkplain} // Liknar {@link}, men utan kodteckensnitt.
{@code} // För bokstavskod, till exempel HTML-taggar. Till exempel: {@code <html> </html>}. Detta kommer emellertid att använda ett teckensnitt med en enda färg. För att få samma resultat utan monospace-teckensnittet, använd {@ literal}.
{@ literal} // Samma som {@code}, men utan det monografiska teckensnittet.
{@value} // Visar värdet på ett statiskt fält: Värdet på JFrame # EXIT_ON_CLOSE är {@value}. Eller så kan du länka till ett visst fält: använder appnamnet {@value AppConstants # APP_NAME}.
{@docRoot} // Rotmappen för JavaDoc HTML relativt den aktuella filen. Exempel: <a href="{@docRoot}/credits.html"> Credits </a>.
HTML är tillåtet: <kod> "Hejkakor" .substräng (3) </code>.
* / - slut på JavaDoc-deklarationen

Anmärkningar

Javadoc är ett verktyg som ingår i JDK som gör att kommentarer i kod kan konverteras till en HTML-dokumentation. Java API-specifikationen genererades med Javadoc. Detsamma gäller för mycket av dokumentationen från tredjepartsbibliotek.

Klassdokumentation

Alla Javadoc-kommentarer börjar med en blockkommentar följt av en asterisk ( /** ) och slutar när blockkommentaren gör ( */ ). Valfritt kan varje rad börja med godtyckligt vitrum och en enda asterisk; dessa ignoreras när dokumentationsfilerna genereras.

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

Samma taggar och format som används för Classes kan också användas för Enums och Interfaces .

Metoddokumentation

/**
 * 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;
}

Fältdokumentation

/**
 * 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";

Paketdokumentation

Java SE 5

Det är möjligt att skapa paketdokumentation i Javadocs med en fil som heter package-info.java . Denna fil måste formateras enligt nedan. Ledande whitespace och asterisker valfritt, finns vanligtvis i varje rad av formateringsskäl

/**
 * 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.

I ovanstående fall måste du lägga detta package-info.java i mappen i Java-paketet com.example.foo .

länkar

Länk till andra Javadocs görs med @link taggen:

/**
 * 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} 
 */

Med taggen @see du lägga till element i avsnittet Se också . Liksom @param eller @return är platsen där de visas inte relevant. Specifikationen säger att du ska skriva det efter @return .

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

Om du vill lägga till länkar till externa resurser kan du bara använda HTML <a> -taggen. Du kan använda den inline var som helst eller inne i både @link och @see taggar.

/**
 * 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>
 */

Bygga Javadocs från kommandoraden

Många IDE: er ger stöd för att generera HTML från Javadocs automatiskt; vissa byggverktyg (till exempel Maven och Gradle ) har också plugins som kan hantera HTML-skapandet.

Dessa verktyg krävs dock inte för att generera Javadoc HTML; detta kan göras med hjälp av kommandoraden javadoc verktyget.

Den mest grundläggande användningen av verktyget är:

javadoc JavaFile.java

Vilket kommer att generera HTML från Javadoc-kommentarerna i JavaFile.java .

En mer praktisk användning av kommandoradsverktyget, som kommer att läsa rekursivt alla java-filer i [source-directory] [package.name] , skapa dokumentation för [package.name] och alla underpaket och placera den genererade HTML-filen i [docs-directory] är:

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

Inline koddokumentation

Förutom Javadoc kan dokumentationskoden dokumenteras inline.

Enkomlinjekommentarer startas av // och kan placeras efter ett uttalande på samma rad, men inte förut.

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

Kommentarer med flera linjer definieras mellan /* och */ . De kan sträcka sig över flera rader och kan till och med ha placerats mellan uttalanden.

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

JavaDocs är en speciell form av kommentarer med flera linjer, börjar med /** .

Eftersom för många inline-kommentarer kan minska kodens läsbarhet bör de användas glesa om koden inte är tillräckligt självklar eller designbeslutet inte är uppenbart.

Ett ytterligare användningsfall för kommentarer på en rad är användningen av TAG: er, som är korta, konventionsdrivna nyckelord. Vissa utvecklingsmiljöer känner igen vissa konventioner för sådana enda kommentarer. Vanliga exempel är

//TODO
//FIXME

Eller ge ut referenser, dvs. för Jira

//PRJ-1234

Kodavsnitt i dokumentationen

Det kanoniska sättet att skriva kod i dokumentationen är med {@code } -konstruktionen. Om du har multiline code wrap inuti <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 {

Ibland kan du behöva lägga en komplex kod i javadoc-kommentaren. @ -Tecknet är särskilt problematiskt. Användningen av den gamla <code> -taggen bredvid {@literal } -konstruktionen löser problemet.

/**
 * 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

Licensierat under CC BY-SA 3.0

Inte anslutet till Stack Overflow

Java Language
Dokumentera Java-kod

Sök…