streamalism.org

1. Oversigt

God API-dokumentation er en af ​​de mange faktorer, der bidrager til den samlede succes for et softwareprojekt.

Heldigvis leverer alle moderne versioner af JDK Javadoc-værktøjet - til generering af API-dokumentation fra kommentarer til stede i kildekoden.

Forudsætninger:

1. JDK 1.4 (JDK 7+ anbefales til den nyeste version af Maven Javadoc plugin)
2. JDK /beholder mappe føjet til STI miljøvariabel
3. (Valgfrit) en IDE med indbyggede værktøjer

2. Javadoc-kommentarer

Lad os starte med kommentarer.

Javadoc-kommentarstrukturen ligner meget en almindelig kommentar med flere linjer, men nøgleforskellen er den ekstra stjerne i starten:

// Dette er en enkelt linjekommentar / * * Dette er en regelmæssig kommentar med flere linier * / / ** * Dette er en Javadoc * /

Kommentarer i Javadoc-stil kan også indeholde HTML-tags.

2.1. Javadoc-format

Javadoc-kommentarer kan placeres over enhver klasse, metode eller felt, som vi vil dokumentere.

Disse kommentarer består ofte af to sektioner:

1. Beskrivelsen af, hvad vi kommenterer
2. De enkeltstående blokmærker (markeret med "@”Symbol), der beskriver specifikke metadata

Vi bruger nogle af de mere almindelige bloktag i vores eksempel. For en komplet liste over blokmærker, se referenceguiden.

2.2. Javadoc på klasseniveau

Lad os se på, hvordan en Javadoc-kommentar på klasseniveau ville se ud:

/ ** * Hero er den vigtigste enhed, vi vil bruge til. . . * * Se klassen {@link com.baeldung.javadoc.Person} for ægte identitet * @forfatter Captain America * * / offentlig klasse SuperHero udvider person {// felter og metoder}

Vi har en kort beskrivelse og to forskellige blokmærker - enkeltstående og inline:

• Selvstændige tags vises efter beskrivelsen med tagget som det første ord i en linje, f.eks @forfatter tag
• Indbyggede tags vises muligvis hvor som helst og er omgivet af krøllede parenteserf.eks @link tag i beskrivelsen

I vores eksempel kan vi også se, at der bruges to slags blok tags:

• {@link} giver et indbygget link til en henvist del af vores kildekode
• @forfatter navnet på forfatteren, der tilføjede den klasse, metode eller felt, der kommenteres

2.3. Javadoc på feltniveau

Vi kan også bruge en beskrivelse uden nogen blokmærker som denne inde i vores SuperHero klasse:

/ ** * Det offentlige navn på en helt, der er almindeligt kendt * / privat String heroName;

Private felter har ikke Javadoc genereret til dem, medmindre vi udtrykkeligt videregiver -privat indstilling til Javadoc-kommandoen.

2.4. Javadoc på metodeniveau

Metoder kan indeholde en række forskellige Javadoc-blok tags.

Lad os se på en metode, vi bruger:

/** * 
Dette er en simpel beskrivelse af metoden. . . * Superman! * 
 * @param incomingDamage mængden af ​​indkommende skade * @returner mængden af ​​heltehelt efter angreb * @ see HERO-402 * @since 1.0 * / public int heldigvisAttacked (int incomingDamage) {// gør ting returnere 0; }

Det angrebet med succes metoden indeholder både en beskrivelse og adskillige enkeltstående blok tags.

Der er mange blokmærker, der hjælper med at generere korrekt dokumentation, og vi kan inkludere alle mulige forskellige slags informationer. Vi kan endda bruge grundlæggende HTML-tags i kommentarerne.

Lad os gå over de tags, vi støder på i eksemplet ovenfor:

• @param giver en hvilken som helst nyttig beskrivelse af en metodes parameter eller input, som den kan forvente
• @Vend tilbage giver en beskrivelse af, hvad en metode vil eller kan returnere
• @se genererer et link svarende til {@link} tag, men mere i sammenhæng med en reference og ikke indbygget
• @siden angiver, hvilken version klassen, feltet eller metoden blev føjet til projektet
• @version angiver versionen af ​​softwaren, der ofte bruges med% I% og% G% makroer
• @kaster bruges til yderligere at forklare de tilfælde, softwaren forventer en undtagelse
• @ forældet giver en forklaring på, hvorfor kode blev udfaset, hvornår den muligvis er udfaset, og hvilke alternativer der er

Selvom begge sektioner er teknisk valgfri, har vi brug for mindst en til Javadoc-værktøjet for at generere noget meningsfuldt.

3. Javadoc-generation

For at generere vores Javadoc-sider, vil vi se på kommandolinjeværktøjet, der leveres med JDK og Maven-pluginet.

3.1. Javadoc kommandolinjeværktøj

Javadoc-kommandolinjeværktøjet er meget kraftfuldt, men har en vis kompleksitet knyttet til det.

Kører kommandoen javadoc uden nogen indstillinger eller parametre vil det resultere i en fejl og outputparametre, som den forventer.

Vi bliver i det mindste nødt til at specificere, hvilken pakke eller klasse vi ønsker, at der genereres dokumentation til.

Lad os åbne en kommandolinje og navigere til projektmappen.

Forudsat at klasserne er alle i src mappe i projektmappen:

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

Dette genererer dokumentation i et kaldet bibliotek dok som specificeret med -d flag. Hvis der findes flere pakker eller filer, skal vi give dem alle.

Brug af en IDE med den indbyggede funktionalitet er selvfølgelig lettere og generelt anbefales.

3.2. Javadoc med Maven-plugin

Vi kan også bruge Maven Javadoc-pluginet:

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

I projektets basismappe kører vi kommandoen til at generere vores Javadocs til en mappe i target \ site:

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

Maven-pluginet er meget kraftfuldt og letter kompliceret dokumentgenerering problemfrit.

Lad os nu se, hvordan en genereret Javadoc-side ser ud:

Vi kan se et træbillede af klasserne vores SuperHero klasse udvides. Vi kan se vores beskrivelse, felter og metode, og vi kan klikke på links for at få flere oplysninger.

En detaljeret oversigt over vores metode ser sådan ud:

3.3. Brugerdefinerede Javadoc-tags

Ud over at bruge foruddefinerede blokmærker til at formatere vores dokumentation, Vi kan også oprette brugerdefinerede blokmærker.

For at gøre det skal vi bare medtage en -mærke indstilling til vores Javadoc-kommandolinje i formatet ::.

For at oprette et brugerdefineret tag kaldet @Beliggenhed tilladt hvor som helst, som vises i overskriften "Bemærkelsesværdige placeringer" i vores genererede dokument, skal vi køre:

[e-mailbeskyttet]: ~ $ javadoc -tag placering: a: "Bemærkelsesværdige placeringer:" -d doc src \ *

For at kunne bruge dette tag kan vi tilføje det til blokafsnittet i en Javadoc-kommentar:

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

Maven Javadoc-pluginet er fleksibelt nok til også at tillade definitioner af vores brugerdefinerede tags i vores pom.xml.

For at oprette det samme tag ovenfor til vores projekt kan vi tilføje følgende til sektion af vores plugin:

... placering en bemærkelsesværdige steder: ...

Denne måde giver os mulighed for at specificere det brugerdefinerede tag en gang i stedet for at specificere det hver gang.

4. Konklusion

Denne hurtige introduktionsvejledning dækkede, hvordan man skriver grundlæggende Javadocs og genererer dem med Javadoc-kommandolinjen.

En nemmere måde at generere dokumentationen på ville være at bruge alle indbyggede IDE-muligheder eller inkludere Maven-pluginet i vores pom.xml fil og kør de relevante kommandoer.

Kodeprøverne kan som altid findes på GitHub.