Dokumentér din Java-kode automatisk med Javadoc

Hvis du laver nogen form for programmering, vil du være klar over, at en af ​​de mest kedelige opgaver er at dokumentere din kode. Uanset om du finder det lettere irriterende eller en opgave, som du står over for med absolut frygt, er kodedokumentation afgørende. Andre skal forstå, hvordan din kode fungerer, og du kan endda være en af ​​dem, hvis du læser den på et senere tidspunkt!

Java giver bekvemt en indbygget løsning på problemet: Javadoc.

Javadoc kan hjælpe dig med at dokumentere din kode automatisk

Forhåbentlig følger du allerede med god kodningspraksis og inkludere forklarende kommentarer i din kode. Selvom denne type kommentarer i koden bestemt er nyttig, giver den ikke rigtig noget, der kan sammenlignes med en manual.

Selvfølgelig kan en anden programmør kigge din kode igennem og læse om de specifikke klasser, metoder og funktioner, der er foran ham. Det er dog ekstremt svært at få et godt overblik over al koden eller finde funktioner, der kan være nyttige, når du ikke ved, at de findes. Javadoc har til formål at løse det problem.

Javadoc genererer automatisk en detaljeret og læsevenlig HTML-manual til al din kode. Det bedste af det hele gør det ved at bruge kodekommentarer, som du sikkert allerede er ved at skrive.

Hvad er Javadoc præcist, og hvordan virker det?

Javadoc er et selvstændigt program, der leveres sammen med Oracles Java Development Kit (JDK) udgivelser. Faktisk kan du ikke downloade det separat. Når du downloader og installer en af ​​Oracles JDK-versioner, vil den også installere Javadoc.

Når du kører det, genererer Javadoc HTML-dokumentation fra specielt formaterede kommentarer i din Java-kildekode. Denne proces skaber mere nyttig, læsbar dokumentation, samtidig med at den opmuntrer til bedste praksis.

I en nøddeskal gør Javadoc det muligt for dig at skrive din kode og dens dokumentation på samme tid. Det forenkler din arbejdsgang og giver dig mulighed for at udnytte din tid mere effektivt.

Javadoc fungerer ved at parse specielt formaterede kommentarer i din kode og konvertere dem til HTML-output. Den eneste ændring, du virkelig skal foretage, er at inkludere visse strenge i dine kommentarer. Disse lader Javadoc vide, hvad du vil inkludere i den endelige dokumentation.

Javadoc-kommentarer skal umiddelbart gå forud for en klasse-, felt-, konstruktør- eller metodeerklæring. Selve kommentaren skal:

• Begynd med de tre tegn /**.
• Medtag en stjerne i begyndelsen af ​​hver ny linje.
• Luk med de to karakterer */.

I kommentarerne kan du inkludere HTML i det endelige output og inkludere tags, der genererer links til relevante dele af din kodebase. Du kan endda bruge ting som HTML-billedtags til at inkludere billeder i den endelige dokumentation. Når du først har vænnet dig til formatet og de tilgængelige tags, er det en leg at skrive sådanne kommentarer.

Her er et eksempel for at illustrere simple Javadoc-kommentarer, der beskriver en funktion, der henter et billede fra en URL og udskriver det på skærmen. Kommentaren går umiddelbart forud for funktionen og beskriver, hvad den gør. Denne kommentarblok gør også brug af tre sektionsspecifikke tags: @param, @Vend tilbage, og @se.

/**
* Returnerer et billedobjekt, som derefter kan males på skærmen.
* URL-argumentet skal angive en absolut {@link URL}. Navnet
* argument er en specifikation, der er relativ til url-argumentet.
* 

* Denne metode vender altid tilbage med det samme, uanset om den
* billedet findes. Hvornår dette applet forsøger at tegne billedet på
* på skærmen, vil dataene blive indlæst. De grafiske primitiver
* der tegner billedet vil trinvist male på skærmen.
*
* @param url en absolut URL, der angiver billedets basisplacering
* @param navngiv placeringen af ​​billedet i forhold til url-argumentet
* @Vend tilbage billedet på den angivne URL
* @se Billede
*/
offentlig Billede getImage(URL url, strengnavn){
prøve {
Vend tilbage getImage(ny URL(url, navn));
 } fangst (MalformedURLEexception e) {
Vend tilbagenul;
 }
}

Når Javadoc behandler koden ovenfor, genererer den en webside, der ligner følgende:

En browser gengiver Javadoc-output på nogenlunde samme måde, som den viser ethvert HTML-dokument. Javadoc ignorerer ekstra mellemrum og linjeskift, medmindre du bruger HTML-tags til at oprette dette mellemrum.

De @tags, der bruges i slutningen af ​​kommentaren, genererer Parametre, Vender tilbage, og Se også afsnit, du ser.

Du bør følge @param tag med navnet på parameteren, et mellemrum og en beskrivelse af den. I ovenstående tilfælde er der to parametre: url og navn. Bemærk, at begge vises under den samme Parameter-overskrift i dokumentationsoutputtet. Du kan angive så mange parametre, som er nødvendige for den funktion eller metode, du beskriver.

Det @Vend tilbage tag dokumenterer den værdi, som funktionen returnerer, hvis overhovedet. Det kan være en simpel et-ords beskrivelse eller mange sætninger, alt efter omstændighederne.

Det @se tag giver dig mulighed for at mærke andre funktioner, der er relaterede eller relevante. I dette tilfælde refererer @see-tagget til en anden funktion kaldet blot Image. Bemærk, at referencer lavet med dette tag er klikbare links, hvilket gør det muligt for en læser at hoppe til det refererede element i den endelige HTML.

Der er flere tags tilgængelige, såsom @version, @author, @exception og andre. Når de bruges rigtigt, hjælper tags med at relatere varer til hinanden og gør det nemt at navigere gennem dokumentationen.

Kører Javadoc på din kildekode

Du påberåber Javadoc på kommandolinjen. Du kan køre det på enkelte filer, hele mapper, java-pakker eller på tværs af en liste over individuelle filer. Som standard vil Javadoc generere HTML-dokumentationsfilerne i det bibliotek, hvor du indtaster kommandoen. For at få hjælp til de specifikke tilgængelige kommandoer skal du blot indtaste:

javadoc --Hjælp

For at se præcis, hvad Javadoc kan gøre mere detaljeret, tjek den officielle dokumentation fra Oracle. For at oprette et hurtigt sæt dokumentation på en enkelt fil eller mappe, kan du indtaste javadoc på kommandolinjen efterfulgt af et filnavn eller jokertegn.

javadoc ~/code/filnavn.java
javadoc ~/code/*.java

Ovenfor er en liste over de filer og mapper, som Javadoc har oprettet. Som du kan se, er der en del af dem. Af denne grund skal du være sikker på, at du ikke er i samme mappe som din kildekode, når du kører programmet. At gøre det kan skabe noget rod.

For at se dine nyoprettede dokumenter skal du blot åbne index.html fil i din foretrukne browser. Du får en side som følgende:

Dette er dokumentationen til en enkelt, kort Java-klasse for at demonstrere outputtet. Overskriften viser navnet på klassen såvel som de metoder, der er inkluderet i den. Rulning ned afslører mere detaljerede definitioner af hver af klassemetoderne.

Som du kan se, er denne type dokumentation uvurderlig for enhver type Java-projekt, især store med mange tusinde linjer kode. Det ville være en udfordring at lære om en stor kodebase ved at læse dens kildekode. Javadoc-sider gør denne proces meget hurtigere og nemmere at følge.

Javadoc kan hjælpe dig med at holde din Java-kode og al relevant dokumentation organiseret og nem at bruge. Uanset om du gør det for dit glemsomme fremtidige jeg eller for at gøre tingene lettere for et stort team, Javadoc er et kraftfuldt værktøj, der kan ændre den måde, du skriver og interagerer med din Java-kodning på projekter.

De 8 bedste Java-blogs til programmører

Læs Næste