Dokumentera din Java-kod automatiskt med Javadoc

Om du gör någon form av programmering är du väl medveten om att en av de tråkigaste uppgifterna är att dokumentera din kod. Oavsett om du tycker att det är lätt irriterande eller ett åtagande som du står inför med absolut rädsla, är koddokumentation avgörande. Andra måste förstå hur din kod fungerar, och du kanske till och med är en av dem om du läser den vid ett senare tillfälle!

Java tillhandahåller bekvämt en inbyggd lösning på problemet: Javadoc.

Javadoc kan hjälpa dig att dokumentera din kod automatiskt

Förhoppningsvis följer du redan bra kodningsmetoder och inkludera förklarande kommentarer i din kod. Även om den här typen av kommentarer i koden verkligen är till hjälp, ger den inte riktigt något som kan jämföras med en manual.

Visst, en annan programmerare kan titta igenom din kod och läsa om de specifika klasserna, metoderna och funktionerna som finns framför honom. Det är dock extremt svårt att få en bra överblick över all kod eller hitta funktioner som kan vara användbara när du inte vet att de finns. Javadoc syftar till att lösa det problemet.

Javadoc genererar en detaljerad och läsvänlig HTML-manual för all din kod automatiskt. Bäst av allt, det gör det genom att använda kodkommentarer som du förmodligen redan skriver.

Vad är Javadoc exakt och hur fungerar det?

Javadoc är ett fristående program som levereras med Oracles Java Development Kit (JDK)-utgåvor. Faktum är att du inte kan ladda ner det separat. När du laddar ner och installera en av Oracles JDK-versioner, kommer den också att installera Javadoc.

När du kör det genererar Javadoc HTML-dokumentation från speciellt formaterade kommentarer i din Java-källkod. Denna process skapar mer användbar och läsbar dokumentation samtidigt som den uppmuntrar bästa praxis.

I ett nötskal, Javadoc gör det möjligt för dig att skriva din kod och dess dokumentation samtidigt. Det förenklar ditt arbetsflöde och gör att du kan använda din tid mer effektivt.

Javadoc fungerar genom att analysera speciellt formaterade kommentarer i din kod och konvertera dem till HTML-utdata. Den enda förändring du verkligen behöver göra är att inkludera vissa strängar i dina kommentarer. Dessa låter Javadoc veta vad du vill inkludera i den slutliga dokumentationen.

Javadoc-kommentarer bör omedelbart föregå en klass-, fält-, konstruktor- eller metoddeklaration. Själva kommentaren ska:

• Börja med de tre karaktärerna /**.
• Inkludera en asterisk i början av varje ny rad.
• Stäng med de två karaktärerna */.

I kommentarerna kan du inkludera HTML i det slutliga resultatet och inkludera taggar som genererar länkar till relevanta delar av din kodbas. Du kan till och med använda saker som HTML-bildtaggar för att inkludera bilder i den slutliga dokumentationen. När du väl har vant dig vid formatet och tillgängliga taggar är det enkelt att skriva sådana kommentarer.

Här är ett exempel för att illustrera enkla Javadoc-kommentarer som beskriver en funktion som hämtar en bild från en URL och skriver ut den på skärmen. Kommentaren föregår omedelbart funktionen och beskriver vad den gör. Det här kommentarsblocket använder också tre avsnittsspecifika taggar: @param, @lämna tillbaka, och @ser.

/**
* Returnerar ett bildobjekt som sedan kan målas på skärmen.
* URL-argumentet måste ange en absolut {@länk URL}. Namnet
* argument är en specificator som är relativ till url-argumentet.
* 

* Denna metod returnerar alltid omedelbart, oavsett om
*bilden finns. När detta applet försöker rita bilden på
* på skärmen kommer data att laddas. De grafiska primitiverna
* som ritar bilden kommer stegvis att målas på skärmen.
*
* @param url en absolut URL som anger bildens basplats
* @param namnge platsen för bilden, i förhållande till url-argumentet
* @lämna tillbaka bilden på den angivna webbadressen
* @ser Bild
*/
offentlig Bild getImage(URL url, String name){
Prova {
lämna tillbaka getImage(ny URL(url, namn));
 } fånga (MalformedURLEexception e) {
lämna tillbakanull;
 }
}

När Javadoc bearbetar koden ovan genererar den en webbsida som liknar följande:

En webbläsare återger Javadoc-utdata på ungefär samma sätt som den visar alla HTML-dokument. Javadoc ignorerar extra blanksteg och radbrytningar om du inte använder HTML-taggar för att skapa det utrymmet.

@taggarna som används i slutet av kommentaren genererar Parametrar, Returnerar, och Se även avsnitt som du ser.

Du bör följa @param taggen med namnet på parametern, ett mellanslag och en beskrivning av den. I fallet ovan finns det två parametrar: url och namn. Lägg märke till att båda visas under samma rubrik Parametrar i dokumentationen. Du kan lista så många parametrar som behövs för funktionen eller metoden som du beskriver.

De @lämna tillbaka taggen dokumenterar värdet som funktionen returnerar, om överhuvudtaget. Det kan vara en enkel beskrivning på ett ord eller många meningar, beroende på omständigheterna.

De @ser tag låter dig tagga andra funktioner som är relaterade eller relevanta. I det här fallet hänvisar @see-taggen till en annan funktion som helt enkelt kallas Image. Observera att referenser som görs med denna tagg är klickbara länkar, vilket gör att en läsare kan hoppa till det refererade objektet i den slutliga HTML-koden.

Det finns fler taggar tillgängliga som @version, @author, @exception och andra. När de används på rätt sätt hjälper taggar till att relatera föremål till varandra och gör det möjligt att enkelt navigera genom dokumentationen.

Kör Javadoc på din källkod

Du anropar Javadoc på kommandoraden. Du kan köra det på enstaka filer, hela kataloger, java-paket eller över en lista med enskilda filer. Som standard genererar Javadoc HTML-dokumentationsfilerna i katalogen där du anger kommandot. För att få hjälp med de specifika kommandon som finns tillgängliga anger du bara:

javadoc --hjälp

För att se exakt vad Javadoc kan göra mer i detalj, kolla in den officiella dokumentationen från Orakel. För att skapa en snabb uppsättning dokumentation på en enda fil eller katalog kan du gå in javadoc på kommandoraden följt av ett filnamn eller jokertecken.

javadoc ~/code/filnamn.java
javadoc ~/code/*.java

Ovan är en lista över de filer och kataloger som Javadoc har skapat. Som du kan se finns det ganska många av dem. Av denna anledning bör du vara säker på att du inte är i samma katalog som din källkod när du kör programmet. Att göra det kan skapa en hel röra.

För att se dina nyskapade dokument, öppna helt enkelt index.html fil i din föredragna webbläsare. Du kommer att få en sida som följande:

Detta är dokumentationen för en enda kort Java-klass för att demonstrera resultatet. Rubriken visar namnet på klassen samt metoderna som ingår i den. Om du rullar nedåt visas mer detaljerade definitioner av var och en av klassmetoderna.

Som du kan se, för alla typer av Java-projekt, särskilt stora med många tusen rader kod, är denna typ av dokumentation ovärderlig. Det skulle vara en utmaning att lära sig om en stor kodbas genom att läsa igenom dess källkod. Javadoc-sidor gör denna process mycket snabbare och lättare att följa.

Javadoc kan hjälpa dig att hålla din Java-kod och all relevant dokumentation organiserad och enkel att använda. Oavsett om du gör det för ditt glömska framtida jag eller för att göra det lättare för ett stort team, Javadoc är ett kraftfullt verktyg som kan förändra hur du skriver och interagerar med din Java-kodning projekt.

De 8 bästa Java-bloggarna för programmerare

Läs Nästa