streamalism.org

1. Overzicht

Goede API-documentatie is een van de vele factoren die bijdragen aan het algehele succes van een softwareproject.

Gelukkig bieden alle moderne versies van de JDK de Javadoc-tool - voor het genereren van API-documentatie op basis van opmerkingen in de broncode.

Vereisten:

1. JDK 1.4 (JDK 7+ wordt aanbevolen voor de nieuwste versie van de Maven Javadoc-plug-in)
2. Het JDK / bin map toegevoegd aan het PAD omgevingsvariabele
3. (Optioneel) een IDE met ingebouwde tools

2. Javadoc-opmerkingen

Laten we beginnen met opmerkingen.

De structuur van Javadoc-opmerkingen lijkt erg op een gewone opmerking met meerdere regels, maar het belangrijkste verschil is de extra asterisk aan het begin:

// Dit is een opmerking van één regel / * * Dit is een normale opmerking van meerdere regels * / / ** * Dit is een Javadoc * /

Opmerkingen in Javadoc-stijl kunnen ook HTML-tags bevatten.

2.1. Javadoc-indeling

Javadoc-opmerkingen kunnen boven elke klasse, methode of veld worden geplaatst die we willen documenteren.

Deze opmerkingen bestaan ​​doorgaans uit twee delen:

1. De beschrijving van waar we commentaar op geven
2. De zelfstandige bloktags (gemarkeerd met de "@”Symbool) die specifieke metadata beschrijven

We zullen enkele van de meer algemene block-tags in ons voorbeeld gebruiken. Bezoek de naslaggids voor een volledige lijst met bloktags.

2.2. Javadoc op klassenniveau

Laten we eens kijken hoe een Javadoc-opmerking op klassenniveau eruit zou zien:

/ ** * Hero is de belangrijkste entiteit die we zullen gebruiken. . . * * Zie de {@link com.baeldung.javadoc.Person} class voor echte identiteit * @author Captain America * * / public class SuperHero breidt Person {// velden en methoden}

We hebben een korte beschrijving en twee verschillende block-tags: standalone en inline:

• Op zichzelf staande tags verschijnen na de beschrijving met de tag als het eerste woord op een regel, bijvoorbeeld de @schrijver label
• Inline-tags kunnen overal verschijnen en zijn tussen accolades geplaatst, bijvoorbeeld de @koppeling tag in de beschrijving

In ons voorbeeld kunnen we ook zien dat er twee soorten block-tags worden gebruikt:

• {@koppeling} biedt een inline link naar een deel van onze broncode waarnaar wordt verwezen
• @schrijver de naam van de auteur die de klasse, methode of veld heeft toegevoegd waarop wordt gereageerd

2.3. Javadoc op veldniveau

We kunnen ook een beschrijving gebruiken zonder blokkeringstags zoals deze in ons Superheld klasse:

/ ** * De openbare naam van een held die algemeen bekend is * / private String heroName;

Voor privévelden wordt geen Javadoc gegenereerd, tenzij we de -privaat optie toe aan de Javadoc-opdracht.

2.4. Javadoc op Method Level

Methoden kunnen verschillende Javadoc-bloktags bevatten.

Laten we eens kijken naar een methode die we gebruiken:

/** * 
Dit is een eenvoudige beschrijving van de methode. . . * Superman! * 
 * @param incomingDamage de hoeveelheid inkomende schade * @return de hoeveelheid gezondheidsheld heeft na een aanval * @zie HERO-402 * @since 1.0 * / public int succesvolAttacked (int incomingDamage) {// do things return 0; }

De succesvol aangevallen methode bevat zowel een beschrijving als talrijke zelfstandige bloktags.

Er zijn veel bloktags om de juiste documentatie te genereren en we kunnen allerlei verschillende soorten informatie opnemen. We kunnen zelfs eenvoudige HTML-tags gebruiken in de opmerkingen.

Laten we de tags bekijken die we in het bovenstaande voorbeeld tegenkomen:

• @param biedt elke bruikbare beschrijving over de parameter of invoer van een methode die deze mag verwachten
• @terugkeer geeft een beschrijving van wat een methode zal of kan teruggeven
• @zien genereert een link die lijkt op de {@koppeling} tag, maar meer in de context van een referentie en niet inline
• @sinds specificeert welke versie de klasse, het veld of de methode is toegevoegd aan het project
• @versie specificeert de versie van de software, vaak gebruikt met% I% en% G% macro's
• @wint wordt gebruikt om verder uit te leggen in welke gevallen de software een uitzondering zou verwachten
• @verouderd geeft een verklaring waarom code is verouderd, wanneer deze mogelijk is verouderd en wat de alternatieven zijn

Hoewel beide secties technisch optioneel zijn, hebben we er ten minste één nodig voor de Javadoc-tool om iets zinvols te genereren.

3. Javadoc-generatie

Om onze Javadoc-pagina's te genereren, willen we de opdrachtregelhulpprogramma die bij de JDK wordt geleverd, en de Maven-plug-in bekijken.

3.1. Javadoc-opdrachtregelprogramma

De Javadoc-opdrachtregelhulpprogramma is erg krachtig, maar er is enige complexiteit aan verbonden.

De opdracht uitvoeren javadoc zonder enige opties of parameters zal resulteren in een fout en outputparameters die het verwacht.

We zullen op zijn minst moeten specificeren voor welk pakket of welke klasse we documentatie willen genereren.

Laten we een opdrachtregel openen en naar de projectdirectory gaan.

Ervan uitgaande dat de klassen allemaal in de src map in de projectmap:

[e-mail beveiligd]: ~ $ javadoc -d doc src \ *

Dit genereert documentatie in een map met de naam doc zoals gespecificeerd met de -d vlag. Als er meerdere pakketten of bestanden zijn, moeten we ze allemaal leveren.

Het gebruik van een IDE met de ingebouwde functionaliteit is natuurlijk eenvoudiger en wordt over het algemeen aanbevolen.

3.2. Javadoc met Maven-plug-in

We kunnen ook gebruik maken van de Maven Javadoc-plug-in:

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

In de basismap van het project voeren we de opdracht uit om onze Javadocs te genereren naar een map in target \ site:

[e-mail beveiligd]: ~ $ mvn javadoc: javadoc

De Maven-plug-in is zeer krachtig en maakt het genereren van complexe documenten naadloos mogelijk.

Laten we nu eens kijken hoe een gegenereerde Javadoc-pagina eruitziet:

We kunnen een boomstructuur zien van onze klassen Superheld klasse breidt zich uit. We kunnen onze beschrijving, velden en methode zien en we kunnen op links klikken voor meer informatie.

Een gedetailleerd overzicht van onze methode ziet er als volgt uit:

3.3. Aangepaste Javadoc-tags

Naast het gebruik van vooraf gedefinieerde bloktags om onze documentatie op te maken, we kunnen ook aangepaste bloktags maken.

Om dit te doen, hoeven we alleen een -label optie naar onze Javadoc-opdrachtregel in de indeling ::.

Om een ​​aangepaste tag te maken met de naam @plaats overal toegestaan, wat wordt weergegeven in de koptekst "Opmerkelijke locaties" in ons gegenereerde document, moeten we het volgende uitvoeren:

[e-mail beveiligd]: ~ $ javadoc -tag locatie: a: "Opmerkelijke locaties:" -d doc src \ *

Om deze tag te gebruiken, kunnen we deze toevoegen aan het blokgedeelte van een Javadoc-opmerking:

/ ** * Dit is een voorbeeld ... * @locatie New York * @returns blah blah * /

De Maven Javadoc-plug-in is flexibel genoeg om ook definities van onze aangepaste tags in onze pom.xml.

Om dezelfde tag hierboven voor ons project in te stellen, kunnen we het volgende toevoegen aan het sectie van onze plug-in:

... locatie a Opmerkelijke plaatsen: ...

Op deze manier kunnen we de aangepaste tag één keer specificeren, in plaats van deze elke keer op te geven.

4. Conclusie

Deze korte inleidende tutorial behandelde hoe je eenvoudige Javadocs schrijft en deze genereert met de Javadoc-opdrachtregel.

Een eenvoudigere manier om de documentatie te genereren, is om ingebouwde IDE-opties te gebruiken of de Maven-plug-in op te nemen in onze pom.xml bestand en voer de juiste opdrachten uit.

De codevoorbeelden zijn, zoals altijd, te vinden op GitHub.