what is javadoc how use it generate documentation
Deze tutorial legt uit wat de JavaDoc-tool en JavaDoc-opmerkingen zijn en wat de methoden zijn om codedocumentatie te genereren:
JavaDoc is een speciale tool die wordt meegeleverd met de JDK. Het wordt gebruikt om de codedocumentatie van Java-broncode in HTML-indeling te genereren.
Het is een documentatiegenerator voor de Java-taal van Sun Microsystems (momenteel Oracle Corporation).
wat is de beste spywareverwijderaar
Bekijk hier ALLE Java-tutorials.
Wat je leert:
Wat is JavaDoc
Deze tool gebruikt de indeling 'doc comments' om Java-klassen te documenteren. IDE's zoals Eclipse, IntelliJIDEA of NetBeans hebben een ingebouwde JavaDoc-tool om HTML-documentatie te genereren. We hebben ook veel bestandseditors op de markt die de programmeur kunnen helpen bij het produceren van JavaDoc-bronnen.
Behalve broncode documentatie biedt deze tool ook een API die 'doclets' en 'taglets' maakt die we gebruiken om de structuur van een Java-applicatie te analyseren.
Een punt om op te merken is dat deze tool de prestaties van de applicatie op geen enkele manier beïnvloedt, aangezien de compiler alle opmerkingen verwijdert tijdens de compilatie van het Java-programma.
Door commentaar in het programma te schrijven en vervolgens JavaDoc te gebruiken om de documentatie te genereren, helpt dit de programmeur / gebruiker de code te begrijpen.
De HTML-documentatie die door JavaDoc wordt gegenereerd, is API-documentatie. Het parseert de declaraties en genereert een set bronbestanden. Bronbestand beschrijft velden, methoden, constructors en klassen.
Merk op dat voordat we de JavaDoc-tool op onze broncode gebruiken, we speciale JavaDoc-opmerkingen in het programma moeten opnemen.
Laten we nu verder gaan met opmerkingen.
JavaDoc-opmerkingen
De Java-taal ondersteunt de volgende soorten opmerkingen.
# 1) Opmerkingen met één regel: De opmerking van één regel wordt aangeduid met ' ”En wanneer de compiler deze tegenkomt, negeert hij alles wat volgt op deze commentaren tot het einde van de regel.
# 2) Opmerkingen met meerdere regels: Opmerkingen met meerdere regels worden weergegeven met ' Dus bij het tegenkomen van de ‘/ *’ reeks, negeert de compiler alles wat volgt op deze reeks totdat het de afsluitende reeks ‘* /’ tegenkomt.
# 3) Opmerkingen over documentatie: Dit worden Doc-opmerkingen genoemd en ze worden door de tool gebruikt om API-documentatie te genereren. De doc-opmerkingen worden aangegeven als ' /** documentatie */ Zoals we kunnen zien, verschillen deze opmerkingen van de normale opmerkingen die hierboven zijn beschreven. De doc-commentaren kunnen ook HTML-tags bevatten, zoals we binnenkort zullen zien.
Dus om API-documentatie te genereren met behulp van deze tool, moeten we deze documentatie-opmerkingen (doc-opmerkingen) in ons programma opnemen.
Structuur van een JavaDoc-commentaar
De structuur van Doc-commentaar in Java is vergelijkbaar met commentaar met meerdere regels, behalve dat het doc-commentaar een extra asterisk (*) heeft in de openingstag. Dus de documentcommentaar begint met ‘/ **’ in plaats van ‘/ *’.
Bovendien kunnen opmerkingen in JavaDoc-stijl ook HTML-tags bevatten.
JavaDoc-commentaarformaat
Op basis van de programmeerconstructie die we willen documenteren, kunnen we doc-opmerkingen plaatsen boven elke constructie, zoals klasse, methode, veld, enz. Laten we eens kijken naar voorbeelden van de doc-opmerkingen van elk van de constructies.
Klasseniveau-indeling
Het doc-commentaarformaat op klasniveau ziet er als volgt uit:
Zoals hierboven getoond, bevat een doc-opmerking op klasniveau alle details, inclusief de auteur van de klas, eventuele links, enz.
Methode Niveau Formaat
Hieronder wordt een voorbeeld gegeven van een doc-indeling op methodeniveau.
Zoals we in het bovenstaande voorbeeld kunnen zien, kunnen we een willekeurig aantal tags hebben in de doc-opmerking van de methode. We kunnen ook paragrafen hebben in de commentaarbeschrijving die wordt aangegeven door
We hebben ook speciale tags om de geretourneerde waarde (@return) en parameters van de methode (@param) te beschrijven.
Veldniveau-indeling
Het volgende voorbeeld toont de doc-opmerking voor een veld.
Zoals blijkt uit het bovenstaande voorbeeld, kunnen we ook gewone opmerkingen hebben zonder tags. Merk op dat JavaDoc geen documentatie voor privévelden genereert, tenzij we een privé-optie specificeren met het JavaDoc-commando.
Laten we nu de tags bespreken die worden gebruikt bij de doc-opmerkingen.
hoe u een xml-bestand bekijkt
JavaDoc-tags
Java biedt verschillende tags die we kunnen opnemen in de doc-opmerking. Wanneer we deze tags gebruiken, parseert de tool deze tags om een goed opgemaakte API te genereren uit de broncode.
Elke tag is hoofdlettergevoelig en begint met een ‘@’ -teken. Elke tag begint aan het begin van de regel, zoals we kunnen zien aan de hand van de bovenstaande voorbeelden. Anders behandelt de compiler het als een normale tekst. Als afspraak worden dezelfde tags bij elkaar geplaatst.
Er zijn twee soorten tags die we kunnen gebruiken in doc comment.
# 1) Blokkeer tags : Block-tags hebben de vorm van @tag_naam
Block-tags kunnen in de tag-sectie worden geplaatst en volgen de hoofdbeschrijving
# 2) Inline-tags Inline-tags staan tussen accolades en hebben de vorm, {@tag_name} De inline-tags kunnen overal in de doc-opmerking worden geplaatst.
In de volgende tabel staan alle tags die kunnen worden gebruikt in de doc-opmerkingen.
Label | Omschrijving | Geldt voor |
---|---|---|
@return beschrijving | Geeft een beschrijving van de retourwaarde. | Methode |
@author xyz | Geeft de auteur van klasse, interface of opsomming aan. | Klasse, interface, enum |
{@docRoot} | Deze tag heeft het relatieve pad naar de hoofdmap van het document. | Klasse, interface, enum, veld, methode |
@version versie | Specificeert het invoeren van de softwareversie. | Klasse, interface, enum |
@since sinds-tekst | Specificeert sinds wanneer deze functionaliteit bestaat | Klasse, interface, enum, veld, methode |
@zie referentie | Specificeert verwijzingen (links) naar andere documentatie | Klasse, interface, enum, veld, methode |
@param naam beschrijving | Wordt gebruikt om de methode parameter / argument te beschrijven. | Methode |
@exception classname beschrijving | Specificeert een uitzondering die de methode de code ervan kan geven. | Methode |
@throws classname beschrijving | ||
@deprecated beschrijving | Geeft aan of de methode verouderd is | Klasse, interface, enum, veld, methode |
{@inheritDoc} | Wordt gebruikt om de beschrijving van de overschreven methode te kopiëren in geval van overerving | Overheersende methode |
{@linkreferentie} | Biedt verwijzingen of links naar andere symbolen. | Klasse, interface, enum, veld, methode |
{@linkplain referentie} | Hetzelfde als {@link} maar wordt in platte tekst weergegeven. | Klasse, interface, enum, veld, methode |
{@waarde #STATIC_FIELD} | Beschrijf de waarde van een statisch veld. | Statisch veld |
{@code literal} | Wordt gebruikt om de letterlijke tekst in codelettertype op te maken, vergelijkbaar met {@literal} We weten dat we het programma of project niet hoeven te compileren om JavaDoc te genereren. IntelliJIdea Ide biedt een ingebouwde tool om de documentatie te genereren. Volg de onderstaande stappen om de documentatie te genereren met IntelliJIdea.
Hier kunnen we specificeren of we documentatie willen genereren voor het hele project of slechts één klasse etc. We kunnen ook de output directory specificeren waar de documentatiebestanden gegenereerd zullen worden. Er zijn verschillende andere specificaties zoals weergegeven in de bovenstaande afbeelding. Klik op OK als alle parameters zijn opgegeven.
Dit is dus de manier waarop we documentatie kunnen genereren met behulp van deze tool in IntelliJ idea. We kunnen vergelijkbare stappen volgen in andere Java IDE's zoals Eclipse en / of NetBeans. youtube video-omzetter naar mp4-formaat Veel Gestelde VragenV # 1) Wat is het gebruik van JavaDoc? Antwoord: JavaDoc-tool wordt geleverd met JDK. Het wordt gebruikt om de codedocumentatie voor Java-broncode in HTML-indeling te genereren. Deze tool vereist dat de commentaren in de broncode worden geleverd in een vooraf gedefinieerd formaat als /**….*/. Dit worden ook wel doc-opmerkingen genoemd. V # 2) Wat is het voorbeeld van de Java-documentatie? Antwoord: De Java Doc-documentatietool genereert HTML-bestanden zodat we de documentatie vanuit de webbrowser kunnen bekijken. Het echte live voorbeeld van JavaDoc-documentatie is de documentatie voor Java-bibliotheken bij Oracle Corporation, http://download.oracle.com/javase/6/ documenten /brand/. V # 3) Hebben privé-methoden JavaDoc nodig? Antwoord: Nee. Privévelden en methoden zijn alleen voor ontwikkelaars. Het is niet logisch om documentatie te verstrekken voor privémethoden of velden die niet toegankelijk zijn voor de eindgebruiker. Java Doc genereert ook geen documentatie voor privé-entiteiten. V # 4) Wat is JavaDoc Command? Antwoord: Deze opdracht parseert de declaraties en documentcommentaar in Java-bronbestanden en genereert overeenkomstige HTML-documentatiepagina's met documentatie voor openbare en beschermde klassen, geneste klassen, constructors, methoden, velden en interfaces. JavaDoc genereert echter geen documentatie voor privé-entiteiten en anonieme innerlijke klassen. GevolgtrekkingIn deze zelfstudie wordt de JavaDoc-tool beschreven die is verpakt met JDK en die handig is voor het genereren van de codedocumentatie voor Java-broncode in HTML-indeling. We kunnen documentatie genereren door de Java Doc-opdracht uit te voeren via de opdrachttool of door de ingebouwde JavaDoc-functionaliteit te gebruiken die beschikbaar is in de meeste Java IDE's. We hebben gezien hoe we de tool kunnen gebruiken met IntelliJIdea Java IDE om documentatie te genereren. De tutorial legde ook verschillende tags uit die kunnen worden gebruikt met doc-commentaren, zodat de tool gebruiksvriendelijke documentatie kan genereren met alle informatie met betrekking tot de broncode. Bezoek hier om Java vanaf het begin te leren. Aanbevolen literatuur
^
|