Introduksjon til Javadoc

1. Oversikt

God API-dokumentasjon er en av de mange faktorene som bidrar til den generelle suksessen til et programvareprosjekt.

Heldigvis gir alle moderne versjoner av JDK Javadoc-verktøyet - for å generere API-dokumentasjon fra kommentarer som er til stede i kildekoden.

Forutsetninger:

JDK 1.4 (JDK 7+ anbefales for den nyeste versjonen av Maven Javadoc plugin)
JDK / søppel mappen lagt til STI miljøvariabel
(Valgfritt) en IDE som med innebygde verktøy

2. Javadoc-kommentarer

La oss starte med kommentarer.

Javadoc-kommentarstrukturen ser veldig ut som en vanlig kommentar med flere linjer, men nøkkelforskjellen er den ekstra stjernen i begynnelsen:

// Dette er en enkelt linjekommentar / * * Dette er en vanlig kommentar med flere linjer * / / ** * Dette er en Javadoc * /

Kommentarer i Javadoc-stil kan også inneholde HTML-koder.

2.1. Javadoc-format

Javadoc-kommentarer kan plasseres over en hvilken som helst klasse, metode eller felt som vi ønsker å dokumentere.

Disse kommentarene består ofte av to seksjoner:

Beskrivelsen av hva vi kommenterer
De frittstående blokkeringskodene (merket med “@”Symbol) som beskriver spesifikke metadata

Vi bruker noen av de vanligste blokkeringskodene i eksemplet vårt. For en komplett liste over blokkeringsmerker, besøk referanseguiden.

2.2. Javadoc på klassenivå

La oss ta en titt på hvordan en Javadoc-kommentar på klassenivå vil se ut:

/ ** * Helt er hovedenheten vi skal bruke til. . . * * Se klassen {@link com.baeldung.javadoc.Person} for sann identitet * @ forfatter Captain America * * / offentlig klasse SuperHero utvider Person {// felt og metoder}

Vi har en kort beskrivelse og to forskjellige blokkeringsmerker - frittstående og innebygde:

Frittstående koder vises etter beskrivelsen med koden som det første ordet i en linje, f.eks @forfatter stikkord
Inline-tagger kan vises hvor som helst og er omgitt av krøllete parenteser, f.eks @link tag i beskrivelsen

I vårt eksempel kan vi også se to typer blokkeringsmerker som brukes:

{@link} gir en innebygd lenke til en referert del av kildekoden vår
@forfatter navnet på forfatteren som la til klassen, metoden eller feltet som er kommentert

2.3. Javadoc på feltnivå

Vi kan også bruke en beskrivelse uten blokkeringskoder som dette i vår SuperHero klasse:

/ ** * Det offentlige navnet på en helt som er kjent * / private String heroName;

Private felt vil ikke ha Javadoc generert for dem med mindre vi eksplisitt passerer -privat alternativet til Javadoc-kommandoen.

2.4. Javadoc på metodenivå

Metoder kan inneholde en rekke Javadoc-blokkeringsmerker.

La oss ta en titt på en metode vi bruker:

/** * Dette er en enkel beskrivelse av metoden. . . * Supermann! * 
 * @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @ see HERO-402 * @ since 1.0 * / public int successfulAttacked (int incomingDamage) {// do things return 0; }

De vellykket angrepet metoden inneholder både en beskrivelse og mange frittstående blokkoder.

Det er mange blokkeringsmerker for å generere riktig dokumentasjon, og vi kan inkludere alle slags forskjellige typer informasjon. Vi kan til og med bruke grunnleggende HTML-koder i kommentarene.

La oss gå gjennom kodene vi møter i eksemplet ovenfor:

@param gir en hvilken som helst nyttig beskrivelse av metodens parameter eller inngang den kan forvente
@komme tilbake gir en beskrivelse av hva en metode vil eller kan returnere
@se vil generere en lenke som ligner på {@link} tag, men mer i sammenheng med en referanse og ikke innebygd
@siden angir hvilken versjon klassen, feltet eller metoden ble lagt til i prosjektet
@versjon spesifiserer versjonen av programvaren, ofte brukt med% I% og% G% makroer
@kaster brukes til å forklare sakene programvaren forventer et unntak
@ utfaset gir en forklaring på hvorfor koden ble utfaset, når den kan være utfaset, og hva alternativene er

Selv om begge seksjoner er teknisk valgfrie, trenger vi minst en for at Javadoc-verktøyet skal generere noe meningsfylt.

3. Javadoc-generasjon

For å generere Javadoc-sidene, vil vi ta en titt på kommandolinjeverktøyet som følger med JDK og Maven-plugin.

3.1. Javadoc Command Line Tool

Javadoc-kommandolinjeverktøyet er veldig kraftig, men har en viss kompleksitet knyttet til seg.

Kjører kommandoen javadoc uten noen valg eller parametere vil det føre til en feil og utgangsparametere den forventer.

Vi må i det minste spesifisere hvilken pakke eller klasse vi vil at dokumentasjon skal genereres for.

La oss åpne en kommandolinje og navigere til prosjektkatalogen.

Forutsatt at klassene er alle i src mappe i prosjektkatalogen:

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

Dette vil generere dokumentasjon i en katalog som heter dok som spesifisert med -d flagg. Hvis det finnes flere pakker eller filer, må vi oppgi dem alle.

Å bruke en IDE med den innebygde funksjonaliteten er selvfølgelig enklere og generelt anbefalt.

3.2. Javadoc With Maven Plugin

Vi kan også bruke Maven Javadoc-plugin:

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

I grunnkatalogen til prosjektet kjører vi kommandoen for å generere Javadocs til en katalog i target \ site:

[e-postbeskyttet]: ~ $ mvn javadoc: javadoc

Maven-pluginet er veldig kraftig og muliggjør komplisert dokumentgenerering sømløst.

La oss nå se hvordan en generert Javadoc-side ser ut:

Vi kan se en trevisning av klassene våre SuperHero klasse utvider. Vi kan se beskrivelsen, feltene og metoden vår, og vi kan klikke på lenker for mer informasjon.

En detaljert oversikt over metoden vår ser slik ut:

3.3. Egendefinerte Javadoc-koder

I tillegg til å bruke forhåndsdefinerte blokkoder for å formatere dokumentasjonen vår, vi kan også lage egendefinerte blokkeringsmerker.

For å gjøre det, trenger vi bare å inkludere en -stikkord alternativ til vår Javadoc-kommandolinje i formatet ::.

For å lage en egendefinert tag kalt @plassering tillatt hvor som helst, som vises i overskriften "Notable Locations" i vårt genererte dokument, må vi kjøre:

[e-postbeskyttet]: ~ $ javadoc -tag plassering: a: "Bemerkelsesverdige steder:" -d doc src \ *

For å kunne bruke denne taggen, kan vi legge den til i blokkeringsdelen av en Javadoc-kommentar:

/ ** * Dette er et eksempel ... * @lokalisering New York * @returns bla bla * /

Maven Javadoc-plugin er fleksibel nok til å også tillate definisjoner av våre tilpassede koder i vår pom.xml.

For å sette opp den samme koden ovenfor for prosjektet vårt, kan vi legge til følgende i delen av pluginet vårt:

... plassering en bemerkelsesverdige steder: ...

På denne måten kan vi spesifisere den egendefinerte koden en gang, i stedet for å spesifisere den hver gang.

4. Konklusjon

Denne hurtiginnledningsveiledningen dekket hvordan du skriver grunnleggende Javadocs og genererer dem med Javadoc-kommandolinjen.

En enklere måte å generere dokumentasjonen på ville være å bruke eventuelle innebygde IDE-alternativer eller inkludere Maven-pluginet i vårt pom.xml fil og kjør de riktige kommandoene.

Kodeprøvene, som alltid, kan du finne på GitHub.

streamalism.org