Introduktion till Javadoc

1. Översikt

Bra API-dokumentation är en av de många faktorer som bidrar till den totala framgången för ett programvaruprojekt.

Lyckligtvis tillhandahåller alla moderna versioner av JDK verktyget Javadoc - för att generera API-dokumentation från kommentarer som finns i källkoden.

Förutsättningar:

  1. JDK 1.4 (JDK 7+ rekommenderas för den senaste versionen av Maven Javadoc-plugin)
  2. JDK / bin- mappen läggs till i PATH- miljövariabeln
  3. (Valfritt) en IDE som med inbyggda verktyg

2. Kommentarer från Javadoc

Låt oss börja med kommentarer.

Javadoc-kommentarstrukturen ser väldigt ut som en vanlig kommentar med flera rader , men huvudskillnaden är den extra asterisken i början:

// This is a single line comment /* * This is a regular multi-line comment */ /** * This is a Javadoc */

Kommentarer i Javadoc-stil kan också innehålla HTML-taggar.

2.1. Javadoc-format

Javadoc-kommentarer kan placeras ovanför vilken klass, metod eller fält som vi vill dokumentera.

Dessa kommentarer består vanligtvis av två avsnitt:

  1. Beskrivningen av vad vi kommenterar
  2. De fristående blocktaggarna (markerade med symbolen " @ ") som beskriver specifika metadata

Vi använder några av de vanligaste blocktaggarna i vårt exempel. Besök referensguiden för en komplett lista över blocktaggar.

2.2. Javadoc på klassnivå

Låt oss ta en titt på hur en Javadoc-kommentar på klassnivå skulle se ut:

/** * Hero is the main entity we'll be using to . . . * * Please see the {@link com.baeldung.javadoc.Person} class for true identity * @author Captain America * */ public class SuperHero extends Person { // fields and methods }

Vi har en kort beskrivning och två olika blocktagare - fristående och inline:

  • Fristående taggar visas efter beskrivningen med taggen som det första ordet i en rad, t.ex. @author- taggen
  • Inbyggda taggar kan visas var som helst och omges av lockiga parenteser , t.ex. @link- taggen i beskrivningen

I vårt exempel kan vi också se två typer av blocktaggar som används:

  • {@link} tillhandahåller en inbyggd länk till en refererad del av vår källkod
  • @författare namnet på författaren som lade till klassen, metoden eller fältet som kommenteras

2.3. Javadoc på fältnivå

Vi kan också använda en beskrivning utan några blocketiketter som detta i vår SuperHero- klass:

/** * The public name of a hero that is common knowledge */ private String heroName;

Privata fält har inte Javadoc genererat för dem om vi inte uttryckligen överför alternativet -privat till Javadoc-kommandot.

2.4. Javadoc på metodnivå

Metoder kan innehålla en mängd olika Javadoc-blocktaggar.

Låt oss ta en titt på en metod vi använder:

/** * 

This is a simple description of the method. . . * Superman! *

* @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @see HERO-402 * @since 1.0 */ public int successfullyAttacked(int incomingDamage) { // do things return 0; }

Den successfullyAttacked metoden innehåller både en beskrivning och många fristående blocket taggar.

Det finns många blocktaggar som hjälper till att skapa korrekt dokumentation och vi kan inkludera alla typer av olika typer av information. Vi kan till och med använda grundläggande HTML-taggar i kommentarerna.

Låt oss gå igenom taggarna vi stöter på i exemplet ovan:

  • @param ger användbar beskrivning av metodens parameter eller ingång som den kan förvänta sig
  • @return ger en beskrivning av vad en metod kommer eller kan returnera
  • @see genererar en länk som liknar {@link} -taggen, men mer i samband med en referens och inte inline
  • @since anger vilken version klassen, fältet eller metoden har lagts till i projektet
  • @version anger vilken version av programvaran som vanligtvis används med% I% och% G% makron
  • @throws används för att ytterligare förklara de fall programvaran förväntar sig ett undantag
  • @deprecated ger en förklaring till varför koden har upphört att gälla, när den kan ha upphört att gälla och vad alternativen är

Även om båda sektionerna är tekniskt valfria behöver vi minst en för att Javadoc-verktyget ska kunna skapa något meningsfullt.

3. Javadoc-generationen

För att generera våra Javadoc-sidor vill vi ta en titt på kommandoradsverktyget som levereras med JDK och plugin Maven.

3.1. Javadoc Command Line Tool

Javadoc-kommandoradsverktyget är mycket kraftfullt men har en viss komplexitet kopplat till det.

Att köra kommandot javadoc utan några alternativ eller parametrar resulterar i ett fel och utmatningsparametrar som det förväntas.

Vi måste åtminstone ange vilket paket eller klass vi vill att dokumentation ska genereras för.

Låt oss öppna en kommandorad och navigera till projektkatalogen.

Förutsatt att klasserna finns i src- mappen i projektkatalogen:

[email protected]:~$ javadoc -d doc src\*

Detta genererar dokumentation i en katalog som heter doc enligt specifikationen med - d- flaggan. Om det finns flera paket eller filer måste vi tillhandahålla dem alla.

Att använda en IDE med den inbyggda funktionaliteten är naturligtvis enklare och rekommenderas allmänt.

3.2. Javadoc med Maven-plugin

Vi kan också använda Maven Javadoc-plugin:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0  1.8 1.8   ...    

I projektets baskatalog kör vi kommandot för att generera våra Javadocs till en katalog i mål \ site:

[email protected]:~$ mvn javadoc:javadoc

Pluggen Maven är väldigt kraftfull och underlättar komplex dokumentgenerering sömlöst.

Låt oss nu se hur en genererad Javadoc-sida ser ut:

Vi kan se en trädvy av de klasser som vår SuperHero- klass utökar. Vi kan se vår beskrivning, fält och metod, och vi kan klicka på länkar för mer information.

En detaljerad bild av vår metod ser ut så här:

3.3. Anpassade Javadoc-taggar

Förutom att använda fördefinierade blocktaggar för att formatera vår dokumentation kan vi också skapa anpassade blocktaggar.

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

/** * This is an example... * @location New York * @returns blah blah */

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

In order to set up the same tag above for our project, we can add the following to the section of our plugin:

...   location a Notable Places:   ...

This way allows us to specify the custom tag once, instead of specifying it every time.

4. Conclusion

Denna snabba introduktionshandledning behandlade hur man skriver grundläggande Javadocs och genererar dem med Javadoc-kommandoraden.

Ett enklare sätt att generera dokumentationen skulle använda alla inbyggda IDE-alternativ eller inkludera Maven-plugin i vår pom.xml- fil och köra lämpliga kommandon.

Kodproverna, som alltid, finns på GitHub.