Dokumenter Java-koden din automatisk med Javadoc

Hvis du gjør noen form for programmering, vil du være klar over at en av de mest kjedelige oppgavene er å dokumentere koden din. Enten du synes det er lett irriterende eller en forpliktelse du møter med absolutt frykt, er kodedokumentasjon avgjørende. Andre må forstå hvordan koden din fungerer, og du kan til og med være en av dem hvis du leser den på et senere tidspunkt!

Java gir praktisk en innebygd løsning på problemet: Javadoc.

Javadoc kan hjelpe deg med å dokumentere koden din automatisk

Forhåpentligvis følger du allerede god kodingspraksis og inkludere forklarende kommentarer i koden din. Selv om denne typen in-code-kommentarer absolutt er nyttig, gir den egentlig ikke noe som kan sammenlignes med en manual.

Jada, en annen programmerer kan se gjennom koden din og lese om de spesifikke klassene, metodene og funksjonene som ligger foran ham. Det er imidlertid ekstremt vanskelig å få en god oversikt over all koden eller finne funksjoner som kan være nyttige når du ikke vet at de eksisterer. Javadoc har som mål å løse det problemet.

Javadoc vil generere en detaljert og leservennlig HTML-manual for all koden din automatisk. Best av alt, det gjør det ved å bruke kodekommentarer som du sannsynligvis allerede har skrevet.

Hva er egentlig Javadoc og hvordan fungerer det?

Javadoc er et frittstående program som følger med Oracles Java Development Kit (JDK) utgivelser. Faktisk kan du ikke laste den ned separat. Når du laster ned og installer en av Oracles JDK-versjoner, vil den også installere Javadoc.

Når du kjører det, genererer Javadoc HTML-dokumentasjon fra spesielt formaterte kommentarer i Java-kildekoden. Denne prosessen skaper mer nyttig, lesbar dokumentasjon samtidig som den oppmuntrer til beste praksis.

I et nøtteskall, Javadoc gjør det mulig for deg å skrive koden din og dens dokumentasjon samtidig. Det forenkler arbeidsflyten din og lar deg utnytte tiden din mer effektivt.

Javadoc fungerer ved å analysere spesielt formaterte kommentarer i koden din og konvertere dem til HTML-utdata. Den eneste endringen du virkelig trenger å gjøre er å inkludere visse strenger i kommentarene dine. Disse lar Javadoc vite hva du vil inkludere i den endelige dokumentasjonen.

Javadoc-kommentarer bør umiddelbart komme foran en klasse-, felt-, konstruktør- eller metodeerklæring. Selve kommentaren skal:

• Begynn med de tre karakterene /**.
• Ta med en stjerne i begynnelsen av hver ny linje.
• Lukk med de to karakterene */.

I kommentarene kan du inkludere HTML i det endelige resultatet og inkludere tagger som vil generere koblinger til relevante deler av kodebasen din. Du kan til og med bruke ting som HTML-bildekoder for å inkludere bilder i den endelige dokumentasjonen. Når du først har blitt vant til formatet og tilgjengelige tagger, er det enkelt å skrive slike kommentarer.

Her er et eksempel for å illustrere enkle Javadoc-kommentarer som beskriver en funksjon som henter et bilde fra en URL og skriver det ut på skjermen. Kommentaren går umiddelbart foran funksjonen og beskriver hva den gjør. Denne kommentarblokken bruker også tre seksjonsspesifikke tagger: @param, @komme tilbake, og @se.

/**
* Returnerer et bildeobjekt som deretter kan males på skjermen.
* URL-argumentet må spesifisere en absolutt {@lenke URL}. Navnet
* argument er en spesifikasjoner som er relativ til url-argumentet.
* 

* Denne metoden returnerer alltid umiddelbart, uansett om
* bildet finnes. Når dette applet forsøker å tegne bildet på
* på skjermen, vil dataene bli lastet. De grafiske primitivene
* som tegner bildet vil gradvis male på skjermen.
*
* @param url en absolutt URL som angir basisplasseringen til bildet
* @param navngi plasseringen av bildet, i forhold til url-argumentet
* @komme tilbake bildet på den angitte nettadressen
* @se Bilde
*/
offentlig Bilde getImage(URL url, strengnavn){
prøve {
komme tilbake getImage(ny URL(url, navn));
 } å fange (MalformedURLEexception e) {
komme tilbakenull;
 }
}

Når Javadoc behandler koden ovenfor, genererer den en nettside som ligner på følgende:

En nettleser gjengir Javadoc-utdata på omtrent samme måte som den viser et hvilket som helst HTML-dokument. Javadoc ignorerer ekstra mellomrom og linjeskift med mindre du bruker HTML-tagger for å opprette det området.

@-taggene som brukes på slutten av kommentaren genererer Parametere, Returnerer, og Se også seksjoner du ser.

Du bør følge @param tag med navnet på parameteren, et mellomrom og en beskrivelse av den. I tilfellet ovenfor er det to parametere: url og Navn. Legg merke til at begge vises under samme parameteroverskrift i dokumentasjonsutgangen. Du kan liste opp så mange parametere som er nødvendige for funksjonen eller metoden du beskriver.

De @komme tilbake tag dokumenterer verdien som funksjonen returnerer, hvis i det hele tatt. Det kan være en enkel ettordsbeskrivelse eller mange setninger, avhengig av omstendighetene.

De @se tag lar deg merke andre funksjoner som er relaterte eller relevante. I dette tilfellet refererer @see-taggen til en annen funksjon kalt ganske enkelt Image. Merk at referanser laget med denne taggen er klikkbare lenker, som lar en leser hoppe til det refererte elementet i den endelige HTML-koden.

Det er flere tagger tilgjengelig som @version, @author, @exception og andre. Når de brukes riktig, hjelper tags med å relatere varer til hverandre og gjør det mulig å navigere gjennom dokumentasjonen enkelt.

Kjører Javadoc på kildekoden din

Du påkaller Javadoc på kommandolinjen. Du kan kjøre den på enkeltfiler, hele kataloger, java-pakker eller på tvers av en liste over individuelle filer. Som standard vil Javadoc generere HTML-dokumentasjonsfilene i katalogen der du skriver inn kommandoen. For å få hjelp til de spesifikke kommandoene som er tilgjengelige, skriv inn:

javadoc --hjelp

For å se nøyaktig hva Javadoc kan gjøre mer detaljert, sjekk ut den offisielle dokumentasjonen fra Oracle. For å lage et raskt sett med dokumentasjon på en enkelt fil eller katalog kan du gå inn javadoc på kommandolinjen etterfulgt av et filnavn eller jokertegn.

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

Ovenfor er en liste over filene og katalogene som Javadoc har opprettet. Som du kan se, er det ganske mange av dem. Av denne grunn bør du være sikker på at du ikke er i samme katalog som kildekoden når du kjører programmet. Å gjøre det kan skape litt rot.

For å se de nyopprettede dokumentene dine, åpne bare index.html fil i din foretrukne nettleser. Du får en side som denne:

Dette er dokumentasjonen for en enkelt, kort Java-klasse for å demonstrere utdataene. Overskriften viser navnet på klassen samt metodene som er inkludert i den. Når du ruller ned, får du mer detaljerte definisjoner av hver av klassemetodene.

Som du kan se, for alle typer Java-prosjekter, spesielt store med mange tusen linjer med kode, er denne typen dokumentasjon uvurderlig. Det ville være en utfordring å lære om en stor kodebase ved å lese gjennom kildekoden. Javadoc-sider gjør denne prosessen mye raskere og enklere å følge.

Javadoc kan hjelpe deg med å holde Java-koden og all relevant dokumentasjon organisert og enkel å bruke. Enten du gjør det for ditt glemsomme fremtidige jeg eller for å gjøre ting enklere for et stort team, Javadoc er et kraftig verktøy som kan endre måten du skriver og samhandler med Java-kodingen din prosjekter.

De 8 beste Java-bloggene for programmerere

Les Neste