Meny

Hva er JavaDoc og hvordan du bruker det til å generere dokumentasjon

  • Hoved
  • Annen
  • Hva er JavaDoc og hvordan du bruker det til å generere dokumentasjon

what is javadoc how use it generate documentation

Prøv Instrumentet Vårt For Å Eliminere Problemer

Denne veiledningen forklarer hva som er JavaDoc-verktøy og JavaDoc-kommentarer og metoder for å generere kodedokumentasjon:

JavaDoc er et spesialverktøy som er pakket med JDK. Den brukes til å generere kodedokumentasjonen til Java-kildekoden i HTML-format.

Det er en dokumentasjonsgenerator for Java-språket fra Sun Microsystems (for tiden Oracle Corporation).

=> Sjekk ALLE Java-opplæringsprogrammer her.

JavaDoc-verktøy

Hva du vil lære:

Hva er JavaDoc

Dette verktøyet bruker “doc comments” format for å dokumentere Java-klasser. IDEer som Eclipse, IntelliJIDEA eller NetBeans har et innebygd JavaDoc-verktøy for å generere HTML-dokumentasjon. Vi har også mange filredigerere i markedet som kan hjelpe programmereren med å produsere JavaDoc-kilder.

Bortsett fra kildekodedokumentasjon, gir dette verktøyet også API som lager 'doclets' og 'taglets' som vi bruker til å analysere strukturen til et Java-program.

Et poeng å merke seg er at dette verktøyet ikke påvirker ytelsen til applikasjonen på noen måte, siden kompilatoren fjerner alle kommentarene under kompileringen av Java-programmet.

Å skrive kommentarer i programmet og deretter bruke JavaDoc til å generere dokumentasjonen er å hjelpe programmereren / brukeren til å forstå koden.

HTML-dokumentasjonen generert av JavaDoc er API-dokumentasjon. Den analyserer erklæringene og genererer et sett med kildefiler. Kildefilen beskriver felt, metoder, konstruktører og klasser.

Merk at før vi bruker JavaDoc-verktøyet på kildekoden, må vi inkludere spesielle JavaDoc-kommentarer i programmet.

La oss nå gå videre til kommentarer.

JavaDoc-kommentarer

Java-språk støtter følgende typer kommentarer.

# 1) Kommentarer fra en linje: Enkelts kommentaren er betegnet med “ // ”Og når kompilatoren møter disse, ignorerer den alt som følger disse kommentarene til slutten av linjen.

# 2) Flere linjer kommentarer: Kommentarer fra flere linjer er representert ved hjelp av “ /*….*/ ”. Så når vi møter ‘/ *’ sekvensen, ignorerer kompilatoren alt som følger denne sekvensen til den møter den avsluttende sekvensen ‘* /’.

# 3) Dokumentasjonskommentarer: Disse kalles Doc-kommentarer, og de brukes av verktøyet til å generere API-dokumentasjon. Dokumentkommentarene er angitt som “ / ** dokumentasjon * / ”. Som vi kan se, er disse kommentarene forskjellige fra de vanlige kommentarene beskrevet ovenfor. Dokumentkommentarene kan også inneholde HTML-koder i dem, som vi snart vil se.

hva er forskjellen mellom testplan og teststrategi

Så for å generere API-dokumentasjon ved hjelp av dette verktøyet, må vi gi disse dokumentasjonskommentarene (doc-kommentarer) i vårt program.

Strukturen til en JavaDoc-kommentar

Strukturen til Doc-kommentar i Java ligner på flerlinjekommentarer, bortsett fra at doc-kommentaren har en ekstra stjerne (*) i åpningstaggen. Så doc-kommentaren starter med ‘/ **’ i stedet for ‘/ *’.

I tillegg kan JavaDoc-stilkommentarer også ha HTML-koder.

JavaDoc kommentarformat

Basert på programmeringskonstruksjonen som vi ønsker å dokumentere, kan vi plassere dokumentkommentarer over alle konstruksjoner som klasse, metode, felt osv. La oss gå gjennom eksempler på hver av konstruksjonene.

Klassenivåformat

Dokumentkommentarformatet på klassenivå vil se ut 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 dokuments kommentar på klassenivå ha alle detaljene inkludert forfatteren av klassen, koblinger hvis noen, etc.

Metodnivåformat

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

/** *

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 eksemplet ovenfor, kan vi ha et hvilket som helst antall koder i dokumentkommentaren til metoden. Vi kan også ha avsnitt inne i kommentarbeskrivelsen angitt av

...

.

Vi har også spesielle koder for å beskrive returverdien (@return) og parametere for metoden (@param).

Feltnivåformat

Følgende eksempel viser dokumentkommentaren for et felt.

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

Som det fremgår av eksemplet ovenfor, kan vi også ha enkle kommentarer uten tagger. Merk at JavaDoc ikke genererer noen dokumentasjon for private felt med mindre vi spesifiserer et privat alternativ med JavaDoc-kommandoen.

La oss nå diskutere kodene som brukes sammen med dokumentkommentarene.

wifi er standard gateway ikke tilgjengelig

JavaDoc-koder

Java tilbyr forskjellige koder som vi kan inkludere i dokumentkommentaren. Når vi bruker disse kodene, analyserer verktøyet disse kodene for å generere et godt formatert API fra kildekoden.

Hver tag er store og små bokstaver og begynner med et @ -tegn. Hver tag begynner på begynnelsen av linjen som vi kan se fra eksemplene ovenfor. Ellers behandler kompilatoren det som en vanlig tekst. Som en konvensjon er de samme kodene plassert sammen.

Det er to typer koder som vi kan bruke i dokumentkommentarer.

# 1) Blokker koder : Blokkeringsmerker har form av @tag_name .

Blokkeringsmerker kan plasseres i merkeseksjonen og følge hovedbeskrivelsen .

# 2) Inline-koder :Inline-tagger er lukket i krøllete bukseseler og har formen, {@tag_name} . De integrerte kodene kan plasseres hvor som helst inne i dokumentkommentaren.

Tabellen nedenfor viser alle kodene som kan brukes i dokumentkommentarene.

stikkordBeskrivelseGjelder
@ returbeskrivelseGir beskrivelse av returverdien.Metode
@forfatter xyzAngir forfatteren av klasse, grensesnitt eller enum.Klasse, grensesnitt, Enum
{@docRoot}Denne koden har den relative banen til dokumentets rotkatalog.Klasse, grensesnitt, Enum, felt, metode
@versjon versjonSpesifiserer oppføring av programvareversjon.Klasse, grensesnitt, Enum
@ siden siden-tekstSpesifiserer siden når denne funksjonaliteten eksistererKlasse, grensesnitt, Enum, felt, metode
@se referanseSpesifiserer referanser (lenker) til annen dokumentasjonKlasse, grensesnitt, Enum, felt, metode
@param navn beskrivelseBrukes til å beskrive metodeparameter / argument.Metode
@ unntak beskrivelse av klassenavnSpesifiserer unntak som metoden kan kaste inn koden.Metode
@ kaster beskrivelse av klassenavn
@ utdatert beskrivelseSpesifiserer om metoden er utdatertKlasse, grensesnitt, Enum, felt, metode
{@inheritDoc}Brukes til å kopiere beskrivelsen fra den overstyrte metoden i tilfelle arvOverstyrende metode
{@link referanse}Gir referanser eller lenker til andre symboler.Klasse, grensesnitt, Enum, felt, metode
{@linkplain referanse}Samme som {@link}, men vises i ren tekst.Klasse, grensesnitt, Enum, felt, metode
{@verdi #STATIC_FIELD}Beskriv verdien av et statisk felt.Statisk felt
{@code bokstavelig}Brukes til å formatere bokstavelig tekst i kodeskrift som ligner på {@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 at vi ikke trenger å kompilere programmet eller prosjektet for å generere JavaDoc. IntelliJIdea Ide tilbyr et innebygd verktøy for å generere dokumentasjonen. Følg trinnene nedenfor for å generere dokumentasjonen ved hjelp av IntelliJIdea.

  • Klikk på Verktøy -> Generer JavaDoc

Generer JavaDoc

  • Følgende skjermbilde åpnes når du klikker på JavaDoc-verktøyet.

JavaDoc-verktøy åpnet

Her kan vi spesifisere om vi vil generere dokumentasjon for hele prosjektet eller bare en klasse osv. Vi kan også spesifisere utdatakatalogen der dokumentasjonsfilene skal genereres. Det er forskjellige andre spesifikasjoner som vist i figuren ovenfor.

Klikk på OK når alle parametrene er spesifisert.

  • Nå kan vi se prosessen for generering av Java Doc i utgangsvinduet. Et eksempel på Java Doc-utgangsvindu ser ut som vist nedenfor:

JavaDoc utgangsvindu

  • Når generasjonen er fullført, genereres følgende filer.

JavaDoc-generasjon

  • Som vi spesifiserte hovedklassen, genereres filen Main.html. Merk at index.html også har samme innhold som Main.html.
  • Filen help-doc.html inneholder generelle definisjoner av Java-enheter. Et eksempel på innholdet i denne filen er vist nedenfor.

API-dokumenter organisert

  • På samme måte er det gitt et eksempel på innhold i filen Main.html

et eksempel på innhold i filen Main.html

Dermed er dette måten vi kan generere dokumentasjon ved hjelp av dette verktøyet i IntelliJ-ideen. Vi kan følge lignende trinn i andre Java IDEer som Eclipse og / eller NetBeans.

ofte stilte spørsmål

Q # 1) Hva er bruken av JavaDoc?

Svar: JavaDoc-verktøyet kommer med JDK. Den brukes til å generere kodedokumentasjonen for Java-kildekoden i HTML-format. Dette verktøyet krever at kommentarene i kildekoden er gitt i et forhåndsdefinert format som /**….*/. Disse kalles også doc-kommentarer.

Spørsmål nr. 2) Hva er eksemplet på Java-dokumentasjon?

Svar: Java Doc-dokumentasjonsverktøy genererer HTML-filer slik at vi kan se dokumentasjonen fra nettleseren. Det virkelige live-eksemplet på JavaDoc-dokumentasjon er dokumentasjonen for Java-biblioteker på Oracle Corporation, http://download.oracle.com/javase/6/ dokumenter /Brann/.

Spørsmål 3) Trenger private metoder JavaDoc?

Svar: Nei. Private felt og metoder er bare for utviklere. Det er ingen logikk i å gi dokumentasjon for private metoder eller felt som ikke er tilgjengelige for sluttbruker. Java Doc genererer heller ikke dokumentasjon for private enheter.

beste bøkene for å lære cybersikkerhet

Q # 4) Hva er JavaDoc Command?

Svar: Denne kommandoen analyserer erklæringer og dokumentkommentarer i Java-kildefiler og genererer tilsvarende HTML-dokumentasjonssider som inneholder dokumentasjon for offentlige og beskyttede klasser, nestede klasser, konstruktører, metoder, felt og grensesnitt.

JavaDoc genererer imidlertid ikke dokumentasjon for private enheter og anonyme indre klasser.

Konklusjon

Denne opplæringen beskrev JavaDoc-verktøyet pakket med JDK som er nyttig for å generere kodedokumentasjonen for Java-kildekoden i HTML-format. Vi kan generere dokumentasjon ved å enten utføre Java Doc-kommandoen via kommandoverktøy eller ved å bruke den innebygde JavaDoc-funksjonaliteten som er tilgjengelig i de fleste Java IDEer.

Vi så hvordan vi kan bruke verktøyet med IntelliJIdea Java IDE for å generere dokumentasjon. Opplæringen forklarte også forskjellige koder som kan brukes med doc-kommentarer, slik at verktøyet kan generere brukervennlig dokumentasjon som inneholder all informasjon relatert til kildekoden.

=> Besøk her for å lære Java fra bunnen av.

Anbefalt lesing

^