Documenteer uw Java-code automatisch met Javadoc

Als u enige vorm van programmeren uitvoert, weet u heel goed dat het documenteren van uw code een van de meest vervelende taken is. Of je het nu een beetje vervelend vindt of een onderneming waar je absoluut bang voor bent, codedocumentatie is essentieel. Anderen moeten begrijpen hoe uw code werkt, en u zou zelfs een van hen kunnen zijn als u deze op een later tijdstip leest!

Java biedt handig een ingebouwde oplossing voor het probleem: Javadoc.

Javadoc kan u helpen uw code automatisch te documenteren

Hopelijk volg je al goede codeerpraktijken en neem verklarende opmerkingen op in uw code. Hoewel dit soort commentaar in de code zeker nuttig is, biedt het niet echt iets dat vergelijkbaar is met een handleiding.

Natuurlijk kan een andere programmeur je code bekijken en lezen over de specifieke klassen, methoden en functies die voor hem liggen. Het is echter uiterst moeilijk om een ​​goed overzicht te krijgen van alle code of om functies te vinden die nuttig kunnen zijn als u niet weet dat ze bestaan. Javadoc wil dat probleem oplossen.

Javadoc genereert automatisch een gedetailleerde en leesvriendelijke HTML-handleiding voor al uw code. Het beste van alles is dat het dit doet door code-opmerkingen te gebruiken die u waarschijnlijk al aan het schrijven bent.

Wat is Javadoc precies en hoe werkt het?

Javadoc is een op zichzelf staand programma dat wordt geleverd met Oracle's Java Development Kit (JDK)-releases. U kunt het zelfs niet afzonderlijk downloaden. Wanneer u downloadt en installeer een van Oracle's JDK-versies, zal het ook Javadoc installeren.

Wanneer u het uitvoert, genereert Javadoc HTML-documentatie van speciaal opgemaakte opmerkingen in uw Java-broncode. Dit proces zorgt voor meer bruikbare, leesbare documentatie en moedigt ook best practices aan.

Kortom, Javadoc maakt het voor u mogelijk om uw code en de bijbehorende documentatie tegelijkertijd te schrijven. Het vereenvoudigt uw workflow en stelt u in staat uw tijd efficiënter te besteden.

Javadoc werkt door speciaal opgemaakte opmerkingen in uw code te ontleden en deze om te zetten in HTML-uitvoer. De enige wijziging die u echt moet aanbrengen, is om bepaalde tekenreeksen in uw opmerkingen op te nemen. Deze laten Javadoc weten wat u in de definitieve documentatie wilt opnemen.

Javadoc-opmerkingen moeten onmiddellijk voorafgaan aan een klasse-, veld-, constructor- of methodedeclaratie. De opmerking zelf moet:

• Begin met de drie karakters /**.
• Voeg een asterisk toe aan het begin van elke nieuwe regel.
• Sluit af met de twee karakters */.

Binnen de opmerkingen kunt u HTML opnemen in de uiteindelijke uitvoer en tags opnemen die links naar relevante delen van uw codebase genereren. U kunt zelfs dingen als HTML-afbeeldingstags gebruiken om afbeeldingen in de uiteindelijke documentatie op te nemen. Als u eenmaal gewend bent aan het formaat en de beschikbare tags, is het schrijven van dergelijke opmerkingen een fluitje van een cent.

Hier is een voorbeeld om eenvoudige Javadoc-opmerkingen te illustreren die een functie beschrijven die een afbeelding van een URL haalt en deze op het scherm afdrukt. De opmerking gaat onmiddellijk vooraf aan de functie en beschrijft wat deze doet. Dit commentaarblok maakt ook gebruik van drie sectiespecifieke tags: @param, @opbrengst, en @zien.

/**
* Retourneert een afbeeldingsobject dat vervolgens op het scherm kan worden geschilderd.
* Het url-argument moet een absoluut. specificeren {@koppeling URL}. De naam
* argument is een specificatie die relatief is aan het url-argument.
* 

* Deze methode retourneert altijd onmiddellijk, ongeacht of de
* afbeelding bestaat. Wanneer deze applet probeert de afbeelding te tekenen op
* het scherm, de gegevens worden geladen. De grafische primitieven
* die de afbeelding tekenen, worden stapsgewijs op het scherm weergegeven.
*
* @param url een absolute URL die de basislocatie van de afbeelding geeft
* @param noem de locatie van de afbeelding, relatief aan het url-argument
* @opbrengst de afbeelding op de opgegeven URL
* @zien Afbeelding
*/
openbaar Afbeelding getImage(URL-url, stringnaam){
proberen {
opbrengst getImage(nieuwe URL(url, naam));
 } vangst (Onjuiste URL-uitzondering e) {
opbrengstnul;
 }
}

Wanneer Javadoc de bovenstaande code verwerkt, genereert het een webpagina die lijkt op het volgende:

Een browser geeft Javadoc-uitvoer op vrijwel dezelfde manier weer als elk HTML-document. Javadoc negeert extra witruimte en regeleinden, tenzij u HTML-tags gebruikt om die ruimte te creëren.

De @tags die aan het einde van de opmerking worden gebruikt, genereren de Parameters:, Geeft terug, en Zie ook secties die u ziet.

Je moet de volgen @param tag met de naam van de parameter, een spatie en een beschrijving ervan. In het bovenstaande geval zijn er twee parameters: url en naam. Merk op dat beide verschijnen onder dezelfde kop Parameters in de documentatie-uitvoer. U kunt zoveel parameters opsommen als nodig zijn voor de functie of methode die u beschrijft.

De @opbrengst tag documenteert de waarde die de functie retourneert, of helemaal niet. Het kan een eenvoudige beschrijving van één woord zijn of meerdere zinnen, afhankelijk van de omstandigheden.

De @zien tag stelt u in staat om andere functies te taggen die gerelateerd of relevant zijn. In dit geval verwijst de @see-tag naar een andere functie die eenvoudigweg Image wordt genoemd. Merk op dat verwijzingen met deze tag klikbare links zijn, waardoor een lezer naar het item waarnaar verwezen wordt in de uiteindelijke HTML kan springen.

Er zijn meer tags beschikbaar, zoals @version, @author, @exception en andere. Bij correct gebruik helpen tags om items aan elkaar te relateren en het mogelijk te maken om gemakkelijk door de documentatie te navigeren.

Javadoc uitvoeren op uw broncode

Je roept Javadoc aan op de opdrachtregel. U kunt het uitvoeren op afzonderlijke bestanden, hele mappen, java-pakketten of op een lijst met afzonderlijke bestanden. Standaard genereert Javadoc de HTML-documentatiebestanden in de map waar u de opdracht invoert. Om hulp te krijgen bij de specifieke beschikbare commando's, voert u eenvoudig het volgende in:

javadoc --helpen

Om precies te zien wat Javadoc in meer detail kan doen, bekijk de officiële documentatie van Orakel. Om een ​​snelle set documentatie te maken voor een enkel bestand of map die u kunt invoeren: javadoc op de opdrachtregel gevolgd door een bestandsnaam of jokerteken.

javadoc ~/code/bestandsnaam.java
javadoc ~/code/*.Java

Hierboven ziet u een lijst van de bestanden en mappen die Javadoc heeft gemaakt. Zoals je ziet zijn dat er nogal wat. Om deze reden moet u er zeker van zijn dat u zich niet in dezelfde map bevindt als uw broncode wanneer u het programma uitvoert. Als je dat doet, kan er nogal wat rommel ontstaan.

Om uw nieuw gemaakte documenten te bekijken, opent u gewoon de index.html bestand in uw favoriete browser. U krijgt een pagina zoals de volgende:

Dit is de documentatie voor een enkele, korte Java-klasse om de uitvoer te demonstreren. De koptekst toont de naam van de klasse en de methoden die erin zijn opgenomen. Naar beneden scrollen onthult meer gedetailleerde definities van elk van de klassenmethoden.

Zoals u kunt zien, is dit type documentatie voor elk type Java-project, vooral grote projecten met vele duizenden regels code, van onschatbare waarde. Het zou een uitdaging zijn om meer te weten te komen over een grote codebase door de broncode te lezen. Javadoc-pagina's maken dit proces veel sneller en gemakkelijker te volgen.

Javadoc kan u helpen uw Java-code en alle relevante documentatie overzichtelijk en gebruiksvriendelijk te houden. Of je het nu doet voor je vergeetachtige toekomstige zelf of om het een groot team makkelijker te maken, Javadoc is een krachtig hulpmiddel dat de manier waarop u schrijft en met uw Java-codering werkt, kan veranderen projecten.

De 8 beste Java-blogs voor programmeurs

Lees volgende