Menu

Hvad er JavaDoc, og hvordan man bruger det til at generere dokumentation

  • Vigtigste
  • Andet
  • Hvad er JavaDoc, og hvordan man bruger det til at generere dokumentation

what is javadoc how use it generate documentation

Prøv Vores Instrument Til At Fjerne Problemer

Denne vejledning forklarer, hvad der er JavaDoc-værktøj og JavaDoc-kommentarer og metoder til at generere kodedokumentation:

JavaDoc er et specielt værktøj, der er pakket med JDK. Det bruges til at generere kodedokumentationen for Java-kildekoden i HTML-format.

Det er en dokumentationsgenerator til Java-sproget fra Sun Microsystems (i øjeblikket Oracle Corporation).

=> Tjek ALLE Java-tutorials her.

JavaDoc-værktøj

Hvad du lærer:

Hvad er JavaDoc

Dette værktøj bruger formatet 'doc-kommentarer' til at dokumentere Java-klasser. IDE'er som Eclipse, IntelliJIDEA eller NetBeans har et indbygget JavaDoc-værktøj til at generere HTML-dokumentation. Vi har også mange filredigerere på markedet, der kan hjælpe programmøren med at producere JavaDoc-kilder.

Bortset fra kildekodedokumentation leverer dette værktøj også API, der opretter 'doclets' og 'taglets', som vi bruger til at analysere strukturen i en Java-applikation.

Et punkt at bemærke er, at dette værktøj ikke påvirker applikationens ydeevne på nogen måde, da compileren fjerner alle kommentarerne under kompilering af Java-programmet.

At skrive kommentarer i programmet og derefter bruge JavaDoc til at generere dokumentationen er at hjælpe programmøren / brugeren med at forstå koden.

HTML-dokumentationen genereret af JavaDoc er API-dokumentation. Det analyserer erklæringerne og genererer et sæt kildefiler. Kildefilen beskriver felter, metoder, konstruktører og klasser.

Bemærk, at inden vi bruger JavaDoc-værktøjet på vores kildekode, skal vi medtage specielle JavaDoc-kommentarer i programmet.

Lad os nu gå videre til kommentarer.

JavaDoc-kommentarer

Java-sprog understøtter følgende typer kommentarer.

# 1) Kommentarer til en enkelt linje: Kommentaren med en linje er betegnet med “ // ”Og når kompilatoren møder disse, ignorerer den alt, hvad der følger disse kommentarer indtil slutningen af ​​linjen.

# 2) Kommentarer til flere linjer: Multiline kommentarer er repræsenteret ved hjælp af “ /*….*/ ”. Så når vi støder på '/ *' sekvensen, ignorerer compileren alt, der følger denne sekvens, indtil den møder den afsluttende sekvens '* /'.

# 3) Dokumentationskommentarer: Disse kaldes Doc-kommentarer, og de bruges af værktøjet til at generere API-dokumentation. Dokumentkommentarerne er angivet som “ /** dokumentation */ ”. Som vi kan se, adskiller disse kommentarer sig fra de normale kommentarer beskrevet ovenfor. Dokumentkommentarerne kan også indeholde HTML-tags inde i dem, som vi snart vil se.

datadrevet ramme i eksempel på selen webdriver

Så for at generere API-dokumentation ved hjælp af dette værktøj, skal vi give disse dokumentationskommentarer (doc-kommentarer) i vores program.

Opbygning af en JavaDoc-kommentar

Strukturen for Doc-kommentar i Java svarer til flerlinjekommentarer, bortset fra at doc-kommentaren har en ekstra stjerne (*) i åbningstagget. Så doc-kommentaren starter med '/ **' i stedet for '/ *'.

Derudover kan JavaDoc-stilkommentarer også indeholde HTML-tags.

JavaDoc kommentarformat

Baseret på den programmeringskonstruktion, som vi vil dokumentere, kan vi placere doc-kommentarer over enhver konstruktion som klasse, metode, felt osv. Lad os gennemgå eksempler på hver af konstruktionernes dok-kommentarer.

Klasseformat

Dokumentkommentarformatet på klasseniveau ser ud som vist nedenfor:

/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods }

Som vist ovenfor vil en dokumentkommentar på klasseniveau have alle detaljer inklusive forfatteren af ​​klassen, links, hvis nogen osv.

Metodeniveauformat

Nedenfor er et eksempel på et doc-format på metodeniveau.

/** *

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 fra ovenstående eksempel, kan vi have et vilkårligt antal tags i dokumentets kommentar til metoden. Vi kan også have afsnit inde i kommentarbeskrivelsen angivet af

...

.

Vi har også specielle tags til at beskrive returværdien (@return) og parametre for metoden (@param).

bedste sted at se døbt anime

Format på feltniveau

Følgende eksempel viser doc-kommentaren til et felt.

/** * The public name of a message */ private String msg_txt;

Som det ses af ovenstående eksempel, kan vi også have almindelige kommentarer uden nogen tags. Bemærk, at JavaDoc ikke genererer nogen dokumentation for private felter, medmindre vi angiver en privat mulighed med JavaDoc-kommandoen.

Lad os nu diskutere de tags, der bruges sammen med doc-kommentarerne.

JavaDoc-tags

Java leverer forskellige tags, som vi kan medtage i doc-kommentaren. Når vi bruger disse tags, analyserer værktøjet disse tags for at generere en velformateret API fra kildekoden.

Hvert tag er store og små bogstaver og starter med et '@' tegn. Hvert tag starter i begyndelsen af ​​linjen, som vi kan se fra eksemplerne ovenfor. Ellers behandler compileren det som en normal tekst. Som en konvention er de samme tags placeret sammen.

Der er to typer tags, som vi kan bruge i dok. Kommentar.

# 1) Bloker tags : Blokeringskoder har form af @tag_name .

Bloker tags kan placeres i tag-sektionen og følge hovedbeskrivelsen .

# 2) Inline tags :Inline tags er lukket i krøllede seler og har formen, {@tag_name} . De integrerede tags kan placeres hvor som helst inde i dok. Kommentaren.

Den følgende tabel viser alle de tags, der kan bruges i dokumentkommentarerne.

TagBeskrivelseGælder
@return beskrivelseGiver beskrivelse af returværdi.Metode
@forfatter xyzAngiver forfatteren af ​​klasse, interface eller enum.Klasse, interface, Enum
{@docRoot}Dette tag har den relative sti til dokumentets rodmappe.Klasse, interface, Enum, felt, metode
@version versionSpecificerer indtastning af softwareversion.Klasse, interface, Enum
@ siden siden-tekstSpecificerer siden hvornår denne funktionalitet findesKlasse, interface, Enum, felt, metode
@se referenceSpecificerer referencer (links) til anden dokumentationKlasse, interface, Enum, felt, metode
@param navn beskrivelseBruges til at beskrive metoden parameter / argument.Metode
@exception klassenavn beskrivelseAngiver undtagelse, som metoden kan kaste i sin kode.Metode
@ kaster beskrivelse af klassenavn
@ forældet beskrivelseAngiver, om metoden er forældetKlasse, interface, Enum, felt, metode
{@inheritDoc}Bruges til at kopiere beskrivelsen fra den tilsidesatte metode i tilfælde af arvOverstyrende metode
{@linkreference}Giver referencer eller links til andre symboler.Klasse, interface, Enum, felt, metode
{@linkplain reference}Samme som {@link}, men vises i almindelig tekst.Klasse, interface, Enum, felt, metode
{@værdi #STATIC_FIELD}Beskriv værdien af ​​et statisk felt.Statisk felt
{@code bogstaveligt}Bruges til at formatere den bogstavelige tekst i kodeskrifttype svarende til {@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 ved, at vi ikke behøver at kompilere programmet eller projektet for at generere JavaDoc. IntelliJIdea Ide leverer et indbygget værktøj til at generere dokumentationen. Følg nedenstående trin for at generere dokumentationen ved hjælp af IntelliJIdea.

  • Klik på Værktøjer -> Generer JavaDoc

Generer JavaDoc

  • Følgende skærmbillede åbnes, når der klikkes på JavaDoc-værktøjet.

JavaDoc-værktøjet åbnet

Her kan vi specificere, om vi vil generere dokumentation til hele projektet eller kun en klasse osv. Vi kan også specificere outputkataloget, hvor dokumentationsfilerne skal genereres. Der er forskellige andre specifikationer som vist i ovenstående figur.

Klik på OK, når alle parametre er angivet.

  • Nu kan vi se Java Doc-genereringsprocessen i outputvinduet. Et eksempel på Java Doc-outputvindue ser ud som vist nedenfor:

JavaDoc output-vindue

  • Når generationen er færdig, genereres følgende filer.

JavaDoc-generation

  • Da vi specificerede hovedklassen, genereres filen Main.html. Bemærk, at index.html også har det samme indhold som Main.html.
  • Filen help-doc.html indeholder generelle definitioner af Java-enheder. Et eksempel på indholdet af denne fil er vist nedenfor.

API-dokumenter organiseret

  • Tilsvarende er nedenstående et eksempel på indhold i filen Main.html

et eksempel på indhold i filen Main.html

Således er dette den måde, hvorpå vi kan generere dokumentation ved hjælp af dette værktøj i IntelliJ idé. Vi kan følge lignende trin i andre Java IDE'er som Eclipse og / eller NetBeans.

Ofte stillede spørgsmål

Q # 1) Hvad er brugen af ​​JavaDoc?

Svar: JavaDoc-værktøjet leveres med JDK. Det bruges til at generere kodedokumentationen til Java-kildekoden i HTML-format. Dette værktøj kræver, at kommentarerne i kildekoden leveres i et foruddefineret format som /**….*/. Disse kaldes også doc-kommentarer.

Q # 2) Hvad er eksemplet på Java-dokumentation?

Svar: Java Doc-dokumentationsværktøj genererer HTML-filer, så vi kan se dokumentationen fra webbrowseren. Det virkelige liveeksempel på JavaDoc-dokumentation er dokumentationen til Java-biblioteker på Oracle Corporation, http://download.oracle.com/javase/6/ dok /ild/.

Q # 3) Har private metoder brug for JavaDoc?

Svar: Nej. Private felter og metoder er kun for udviklere. Der er ingen logik i at levere dokumentation til private metoder eller felter, som ikke er tilgængelige for slutbrugeren. Java Doc genererer heller ikke dokumentation for private enheder.

bedste systemvedligeholdelsessoftware til Windows 10

Q # 4) Hvad er JavaDoc Command?

Svar: Denne kommando parser erklæringerne og dokumentkommentarerne i Java-kildefiler og genererer tilsvarende HTML-dokumentationssider, der indeholder dokumentation for offentlige og beskyttede klasser, indlejrede klasser, konstruktører, metoder, felter og grænseflader.

JavaDoc genererer dog ikke dokumentation til private enheder og anonyme indre klasser.

Konklusion

Denne vejledning beskrev JavaDoc-værktøjet pakket med JDK, der er nyttigt til at generere kodedokumentationen til Java-kildekoden i HTML-format. Vi kan generere dokumentation ved enten at udføre Java Doc-kommandoen via kommandoværktøj eller ved hjælp af den indbyggede JavaDoc-funktionalitet, der er tilgængelig i de fleste Java IDE'er.

Vi så, hvordan vi kan bruge værktøjet med IntelliJIdea Java IDE til at generere dokumentation. Vejledningen forklarede også forskellige tags, der kan bruges med doc-kommentarer, så værktøjet kan generere brugervenlig dokumentation, der beskriver alle de oplysninger, der er relateret til kildekoden.

=> Besøg her for at lære Java fra bunden.

Anbefalet læsning

^