what is javadoc how use it generate documentation
Denna handledning förklarar vad som är JavaDoc-verktyg och JavaDoc-kommentarer och metoder för att generera koddokumentation:
JavaDoc är ett specialverktyg som levereras med JDK. Den används för att generera koddokumentationen för Java-källkoden i HTML-format.
Det är en dokumentationsgenerator för Java-språket från Sun Microsystems (för närvarande Oracle Corporation).
=> Kontrollera ALLA Java-handledning här.
Vad du kommer att lära dig:
Vad är JavaDoc
Det här verktyget använder 'doc-kommentarer' -format för att dokumentera Java-klasser. IDE som Eclipse, IntelliJIDEA eller NetBeans har ett inbyggt JavaDoc-verktyg för att generera HTML-dokumentation. Vi har också många filredigerare på marknaden som kan hjälpa programmeraren att producera JavaDoc-källor.
Förutom källkodsdokumentation tillhandahåller detta verktyg också API som skapar 'doclets' och 'taglets' som vi använder för att analysera strukturen i en Java-applikation.
En sak att notera är att detta verktyg inte påverkar programmets prestanda på något sätt eftersom kompilatorn tar bort alla kommentarer under kompileringen av Java-programmet.
Att skriva kommentarer i programmet och sedan använda JavaDoc för att generera dokumentationen är att hjälpa programmeraren / användaren att förstå koden.
HTML-dokumentationen som genereras av JavaDoc är API-dokumentation. Det analyserar deklarationerna och genererar en uppsättning källfiler. Källfilen beskriver fält, metoder, konstruktörer och klasser.
Observera att innan vi använder JavaDoc-verktyget på vår källkod måste vi inkludera speciella JavaDoc-kommentarer i programmet.
Låt oss nu gå vidare till kommentarer.
JavaDoc-kommentarer
Java-språk stöder följande typer av kommentarer.
# 1) Kommentarer med en rad: Enradskommentaren betecknas med “ // ”Och när kompilatorn stöter på dessa ignorerar den allt som följer dessa kommentarer till slutet av raden.
# 2) Flerlinjiga kommentarer: Flerlinjekommentarer representeras med hjälp av “ /*….*/ ”. Så när vi stöter på '/ *' sekvensen ignorerar kompilatorn allt som följer denna sekvens tills den möter den avslutande sekvensen '* /'.
# 3) Dokumentationskommentarer: Dessa kallas Doc-kommentarer och de används av verktyget för att generera API-dokumentation. Dokumentkommentarerna anges som ” / ** dokumentation * / ”. Som vi kan se skiljer sig dessa kommentarer från de normala kommentarer som beskrivs ovan. Dokumentkommentarerna kan också innehålla HTML-taggar inuti dem som vi snart kommer att se.
grundläggande SQL-intervjufrågor och svar för nybörjare pdf
Så för att skapa API-dokumentation med detta verktyg måste vi tillhandahålla dessa dokumentationskommentarer (doc-kommentarer) i vårt program.
Strukturen i en JavaDoc-kommentar
Strukturen för Doc-kommentar i Java liknar flerlinjeskommentarer förutom att doc-kommentaren har en extra asterisk (*) i inledningen. Så dokumentkommentaren börjar med '/ **' istället för '/ *'.
Dessutom kan JavaDoc-stilkommentarer också ha HTML-taggar inuti.
JavaDoc kommentarformat
Baserat på den programmeringskonstruktion som vi vill dokumentera, kan vi placera doc-kommentarer ovanför alla konstruktioner som klass, metod, fält osv.
Klassnivåformat
Dokumentkommentarformatet på klassnivå ser ut som visas nedan:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } Som visas ovan kommer en doc-kommentar på klassnivå att ha alla detaljer inklusive författaren till klassen, länkar om någon, etc.
Metodnivåformat
Nedan ges ett exempel på ett dokumentformat på metodnivå.
/** * simple method description … * JavaDoc! *
* @param msg the message to be printed * @return void * @see JavaDoc * @since 2.0 */ public void printMessage (String msg) { // do things return 0; } Som vi kan se från ovanstående exempel kan vi ha valfritt antal taggar i dokumentets kommentar till metoden. Vi kan också ha stycken i kommentarbeskrivningen som anges av
...
.Vi har också speciella taggar för att beskriva returvärdet (@return) och parametrar för metoden (@param).
Fältnivåformat
Följande exempel visar dokumentkommentaren för ett fält.
/** * The public name of a message */ private String msg_txt;Som vi ser från exemplet ovan kan vi också ha enkla kommentarer utan några taggar. Observera att JavaDoc inte genererar någon dokumentation för privata fält om vi inte anger ett privat alternativ med JavaDoc-kommandot.
Låt oss nu diskutera taggarna som används med dokumentkommentarerna.
JavaDoc-taggar
Java tillhandahåller olika taggar som vi kan inkludera i dokumentkommentaren. När vi använder dessa taggar analyserar verktyget dessa taggar för att skapa ett välformaterat API från källkoden.
Varje tagg är skiftlägeskänslig och börjar med ett '@' - tecken. Varje tagg börjar i början av raden som vi kan se från exemplen ovan. I annat fall behandlar kompilatorn det som en vanlig text. Som en konvention placeras samma taggar tillsammans.
Det finns två typer av taggar som vi kan använda i dokumentkommentarer.
# 1) Blockera taggar : Blocktaggar har formen av @taggnamn .
Blocktaggar kan placeras i taggavsnittet och följa huvudbeskrivningen .
# 2) Inline-taggar :Inbyggda taggar är inneslutna i lockiga hängslen och har formen, {@taggnamn} . Inline-taggarna kan placeras var som helst i dokumentkommentaren.
hur man hittar nätverkssäkerhetsnyckel på Android-telefon
I följande tabell listas alla taggar som kan användas i dokumentkommentarerna.
| Märka | Beskrivning | Gäller för |
|---|---|---|
| @return beskrivning | Ger beskrivning av returvärde. | Metod |
| @författare xyz | Anger författaren till klass, gränssnitt eller enum. | Klass, gränssnitt, Enum |
| {@docRoot} | Den här taggen har den relativa sökvägen till dokumentets rotkatalog. | Klass, gränssnitt, Enum, fält, metod |
| @versionversion | Anger inmatning av programvaruversion. | Klass, gränssnitt, Enum |
| @ sedan sedan-text | Anger sedan när denna funktion finns | Klass, gränssnitt, Enum, fält, metod |
| @se referens | Anger referenser (länkar) till annan dokumentation | Klass, gränssnitt, Enum, fält, metod |
| @param namnbeskrivning | Används för att beskriva metodparametern / argumentet. | Metod |
| @exception klassnamn beskrivning | Anger undantag som metoden kan kasta i sin kod. | Metod |
| @ kastar klassnamnsbeskrivning | ||
| @ föråldrad beskrivning | Anger om metoden är föråldrad | Klass, gränssnitt, Enum, fält, metod |
| {@inheritDoc} | Används för att kopiera beskrivningen från den åsidosatta metoden vid arv | Åsidosättande metod |
| {@länkreferens} | Ger referenser eller länkar till andra symboler. | Klass, gränssnitt, Enum, fält, metod |
| {@linkplain-referens} | Samma som {@link} men visas i klartext. | Klass, gränssnitt, Enum, fält, metod |
| {@värde #STATIC_FIELD} | Beskriv värdet på ett statiskt fält. | Statiskt fält |
| {@code bokstavligt} | Används för att formatera den bokstavliga texten i kodteckensnitt som liknar {@literal}. | Class, Interface, Enum, Field, Method |
| {@literal literal} | Indicates literal text. the enclosed text is interpreted literally without any style formatting. | Class, Interface, Enum, Field, Method |
| {@serial literal} | Description of a serializable field. | Field |
| {@serialData literal} | Documents the data written by the writeExternal( ) or writeObject( ) methods. | Field, Method |
| {@serialField literal} | Describes an ObjectStreamField component. | Field |
Generate Java Doc
To create a JavaDoc you do not need to compile the Java file. We can generate JavaDoc documentation in two ways.
#1) Using JavaDoc Command Via Command Line
The command-line tool allows us to run the command through it.
This command can be executed on a command line and has the following syntax.
user@sth:~$javadoc –d doc src*
In the above command, we assume that all the files and Java classes are in the src folder. Also, the documentation will be generated in the specified ‘doc’ directory.
Note that running the “javadoc” command without any parameters or flags results in an error.
#2) Using The Tool From Any Of The Java IDEs.
All the major Java IDEs provide built-in functionality of generating documentation using the JavaDoc tool.
Using this built-in functionality is easier and also recommended than using a command-line tool to generate Java documentation.
Using JavaDoc With IntelliJIdea
Let’s generate documentation for a simple program using IntelliJIdea IDE.
We will consider the following program for which we have provided doc comments.
/** * Main class * * Please see the {@link www.softwaretestinghelp.com} class for true identity * @author SoftwareTestingHelp * */ public class Main{ /** * main method description … * JavaDoc! *
* @param args() string array * @return void * @see JavaDoc * */ public static void main(String args()) { System.out.println('Hello,World!!'); } } Vi vet att vi inte behöver kompilera programmet eller projektet för att generera JavaDoc. IntelliJIdea Ide tillhandahåller ett inbyggt verktyg för att generera dokumentationen. Följ stegen nedan för att generera dokumentationen med IntelliJIdea.
- Klicka på Verktyg -> Skapa JavaDoc
- Följande skärm öppnas när du klickar på JavaDoc-verktyget.
Här kan vi ange om vi vill generera dokumentation för hela projektet eller bara en klass etc. Vi kan också ange utdatakatalogen där dokumentationsfilerna ska genereras. Det finns olika andra specifikationer som visas i figuren ovan.
Klicka på OK när alla parametrar har angetts.
- Nu kan vi se Java Doc-genereringsprocessen i utdatafönstret. Ett exempel på Java Doc-utgångsfönster ser ut som nedan:
- När generationen är klar genereras följande filer.
- När vi angav huvudklassen genereras filen Main.html. Observera att index.html också har samma innehåll som Main.html.
- Filen help-doc.html innehåller allmänna definitioner av Java-enheter. Ett exempel på innehållet i den här filen visas nedan.
- På samma sätt ges nedan ett exempelinnehåll i filen Main.html
Således är detta sättet vi kan generera dokumentation med hjälp av detta verktyg i IntelliJ-idén. Vi kan följa liknande steg i andra Java IDE som Eclipse och / eller NetBeans.
Vanliga frågor
F # 1) Vad är användningen av JavaDoc?
Svar: JavaDoc-verktyget levereras med JDK. Den används för att generera koddokumentationen för Java-källkoden i HTML-format. Detta verktyg kräver att kommentarerna i källkoden tillhandahålls i ett fördefinierat format som /**….*/. Dessa kallas också doc-kommentarer.
F # 2) Vad är exempel på Java-dokumentation?
Svar: Dokumentationsverktyget för Java Doc genererar HTML-filer så att vi kan se dokumentationen från webbläsaren. Det verkliga liveexemplet på JavaDoc-dokumentation är dokumentationen för Java-bibliotek på Oracle Corporation, http://download.oracle.com/javase/6/ docs /brand/.
F # 3) Behöver privata metoder JavaDoc?
Svar: Nej. Privata fält och metoder är endast för utvecklare. Det finns ingen logik i att tillhandahålla dokumentation för privata metoder eller fält som inte är tillgängliga för slutanvändaren. Java Doc genererar inte heller dokumentation för privata enheter.
hur öppnar man en apk-fil
F # 4) Vad är JavaDoc Command?
Svar: Detta kommando tolkar deklarationerna och dokumentkommentarerna i Java-källfiler och genererar motsvarande HTML-dokumentationssidor som innehåller dokumentation för offentliga och skyddade klasser, kapslade klasser, konstruktörer, metoder, fält och gränssnitt.
JavaDoc genererar dock inte dokumentation för privata enheter och anonyma inre klasser.
Slutsats
Denna handledning beskrev JavaDoc-verktyget förpackat med JDK som är användbart för att generera koddokumentationen för Java-källkod i HTML-format. Vi kan generera dokumentation genom att antingen köra Java Doc-kommandot via kommandoverktyget eller genom att använda den inbyggda JavaDoc-funktionen som finns i de flesta Java IDE.
Vi såg hur vi kan använda verktyget med IntelliJIdea Java IDE för att generera dokumentation. Självstudien förklarade också olika taggar som kan användas med dokumentkommentarer så att verktyget kan generera användarvänlig dokumentation som beskriver all information relaterad till källkoden.
=> Besök här för att lära dig Java från Scratch.
Rekommenderad läsning
- Java Basics: Java Syntax, Java Class och Core Java Concepts
- Java-distribution: Skapande och utförande av Java JAR-fil
- Java Virtual Machine: Hur JVM hjälper till att köra Java-applikationen
- JAVA-handledning för nybörjare: 100+ praktiska Java-videohandledning
- Java-heltal och Java BigInteger-klass med exempel
- Java-komponenter: Java Platform, JDK, JRE och Java Virtual Machine
- Hur skapar man API-dokumentation i brevbäraren?