Java Language => Java-code documenteren

Invoering

Documentatie voor java-code wordt vaak gegenereerd met behulp van javadoc . Javadoc is gemaakt door Sun Microsystems om API-documentatie in HTML-formaat te genereren op basis van Java-broncode. Het gebruik van het HTML-formaat biedt het gemak om gerelateerde documenten met elkaar te kunnen linken.

Syntaxis

/ ** - start van JavaDoc op een klasse, veld, methode of pakket
@author // Om de auteur van de klasse, interface of opsomming te noemen. Het is verplicht.
@version // De versie van die klasse, interface of enum. Het is verplicht. U kunt macro's zoals% I% of% G% gebruiken voor uw broncontrolesoftware om in te vullen bij het afrekenen.
@param // De argumenten (parameters) van een methode of een constructor weergeven. Geef een @param-tag op voor elke parameter.
@return // De retourtypen voor niet-ongeldige methoden weergeven.
@exception // Toont welke uitzonderingen kunnen worden geworpen op de methode of constructor. Uitzonderingen die moeten worden gevangen, moeten hier worden vermeld. Als je wilt, kun je ook degenen opnemen die niet moeten worden gevangen, zoals ArrayIndexOutOfBoundsException. Geef één @exception op voor elke uitzondering die kan worden gegenereerd.
@throws // Hetzelfde als @exception.
@see // Links naar een methode, veld, klasse of pakket. Gebruik in de vorm van pakket. Klasse # iets.
@since // Toen deze methode, veld of klasse werd toegevoegd. Bijvoorbeeld JDK-8 voor een klasse zoals java.util.Optional <T> .
@serial, @serialField, @serialData // Wordt gebruikt om de serialVersionUID te tonen.
@deprecated // Een klasse, methode of veld markeren als verouderd. Een daarvan is bijvoorbeeld java.io.StringBufferInputStream . Bekijk een volledige lijst van bestaande verouderde klassen hier .
{@link} // Vergelijkbaar met @see, maar kan worden gebruikt met aangepaste tekst: {@link #setDefaultCloseOperation (int closeOperation) zie JFrame # setDefaultCloseOperation voor meer info}.
{@linkplain} // Gelijk aan {@link}, maar zonder het codefont.
{@code} // Voor letterlijke code, zoals HTML-tags. Bijvoorbeeld: {@code <html> </html>}. Dit zal echter een monospaced lettertype gebruiken. Gebruik {@literal} om hetzelfde resultaat te krijgen zonder het monospace-lettertype.
{@literal} // Hetzelfde als {@code}, maar zonder het lettertype met één spatie.
{@waarde} // Toont de waarde van een statisch veld: De waarde van JFrame # EXIT_ON_CLOSE is {@waarde}. Of u kunt een koppeling maken naar een bepaald veld: gebruikt de app-naam {@value AppConstants # APP_NAME}.
{@docRoot} // De hoofdmap van de JavaDoc HTML ten opzichte van het huidige bestand. Voorbeeld: <a href="{@docRoot}/credits.html"> Credits </a>.
HTML is toegestaan: <code> "Hallo cookies" .substring (3) </code>.
* / - einde van JavaDoc-aangifte

Opmerkingen

Javadoc is een hulpmiddel bij de JDK waarmee opmerkingen in code kunnen worden omgezet in HTML-documentatie. De Java API-specificatie is gegenereerd met Javadoc. Hetzelfde geldt voor veel van de documentatie van externe bibliotheken.

Klasse documentatie

Alle Javadoc-opmerkingen beginnen met een blokcommentaar, gevolgd door een asterisk ( /** ) en eindigen wanneer de blokcommentaar dat doet ( */ ). Optioneel kan elke regel beginnen met willekeurige witruimte en een enkele asterisk; deze worden genegeerd wanneer de documentatiebestanden worden gegenereerd.

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

Dezelfde tags en opmaak die worden gebruikt voor Classes kunnen ook worden gebruikt voor Enums en Interfaces .

Methode documentatie

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

Velddocumentatie

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

Pakketdocumentatie

Java SE 5

Het is mogelijk om documentatie op pakketniveau in Javadocs te maken met behulp van een bestand met de naam package-info.java . Dit bestand moet worden opgemaakt zoals hieronder. Vooraanstaande witruimte en sterretjes optioneel, meestal aanwezig in elke regel vanwege de opmaak

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

In het bovenstaande geval moet u dit bestand package-info.java in de map van het Java-pakket com.example.foo .

Links

Linken naar andere @link gebeurt met de @link tag:

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

Met de tag @see kunt u elementen toevoegen aan de sectie Zie ook . Net als @param of @return de plaats waar ze verschijnen niet relevant. De specificatie zegt dat je het moet schrijven na @return .

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

Als u links naar externe bronnen wilt toevoegen, kunt u gewoon de HTML <a> -tag gebruiken. Je kunt het overal inline gebruiken of in zowel @link als @see tags.

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

Javadocs bouwen vanaf de opdrachtregel

Veel IDE's bieden ondersteuning voor het automatisch genereren van HTML van Javadocs; sommige build-tools (bijvoorbeeld Maven en Gradle ) hebben ook plug-ins die de HTML-creatie aankunnen.

Deze tools zijn echter niet vereist om de Javadoc HTML te genereren; dit kan worden gedaan met behulp van de opdrachtregel javadoc tool.

Het meest elementaire gebruik van de tool is:

javadoc JavaFile.java

Die HTML genereert uit de Javadoc-opmerkingen in JavaFile.java .

Een meer praktische gebruik van de command line tool, die recursief leest alle dossiers van Java in [source-directory] , creëren documentatie voor [package.name] en alle sub-pakketten, en plaats de gegenereerde HTML in de [docs-directory] is:

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

Inline codedocumentatie

Afgezien van de Javadoc-documentatiecode kan inline worden gedocumenteerd.

Opmerkingen over één regel worden gestart door // en kunnen worden geplaatst na een instructie op dezelfde regel, maar niet eerder.

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

Opmerkingen met meerdere regels worden gedefinieerd tussen /* en */ . Ze kunnen meerdere regels omvatten en kunnen zelfs tussen instructies worden geplaatst.

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

JavaDocs zijn een speciale vorm van reacties met meerdere regels, beginnend met /** .

Omdat te veel inline-opmerkingen de leesbaarheid van code kunnen verminderen, moeten ze spaarzaam worden gebruikt in het geval dat de code niet zelfverklarend genoeg is of het ontwerpbesluit niet duidelijk is.

Een extra gebruiksscenario voor opmerkingen met één regel is het gebruik van TAG's, dit zijn korte, door conventie aangedreven zoekwoorden. Sommige ontwikkelomgevingen herkennen bepaalde conventies voor dergelijke enkele opmerkingen. Veel voorkomende voorbeelden zijn

//TODO
//FIXME

Of geef referenties uit, dat wil zeggen voor Jira

//PRJ-1234

Codefragmenten in documentatie

De canonieke manier om code in de documentatie te schrijven is met de {@code } -constructie. Als u code met meerdere regels in <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 {

Soms moet je misschien wat complexe code in de javadoc-opmerking plaatsen. Het @ -teken is bijzonder problematisch. Het gebruik van de oude <code> -tag naast de {@literal } -constructie lost het probleem op.

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

Licentie onder CC BY-SA 3.0

Niet aangesloten bij Stack Overflow

Java Language
Java-code documenteren

Zoeken…