what is javadoc how use it generate documentation
Ovaj vodič objašnjava što su JavaDoc alat i JavaDoc komentari i metode za generiranje dokumentacije koda:
JavaDoc je poseban alat koji se isporučuje s JDK. Koristi se za generiranje dokumentacije koda izvornog koda Java u HTML formatu.
Generator je dokumentacije za jezik Java tvrtke Sun Microsystems (trenutno Oracle Corporation).
=> Ovdje provjerite SVE Java tutorijale.
Što ćete naučiti:
Što je JavaDoc
Ovaj alat koristi format 'doc comments' za dokumentiranje Java klasa. IDE-i poput Eclipse, IntelliJIDEA ili NetBeans imaju ugrađeni JavaDoc alat za generiranje HTML dokumentacije. Na tržištu također imamo mnogo urednika datoteka koji programeru mogu pomoći u stvaranju JavaDoc izvora.
Osim dokumentacije izvornog koda, ovaj alat također nudi API koji stvara 'doclets' i 'taglete' koje koristimo za analizu strukture Java aplikacije.
Treba napomenuti da ovaj alat ni na koji način ne utječe na performanse aplikacije jer kompajler uklanja sve komentare tijekom kompilacije Java programa.
Pisanje komentara u programu, a zatim korištenje JavaDoca za generiranje dokumentacije pomaže programeru / korisniku da razumije kôd.
HTML dokumentacija koju generira JavaDoc je API dokumentacija. Analizira deklaracije i generira skup izvornih datoteka. Izvorna datoteka opisuje polja, metode, konstruktore i klase.
Prije upotrebe alata JavaDoc na izvornom kodu, u program moramo uključiti posebne komentare JavaDoc.
Krenimo sada na komentare.
JavaDoc komentari
Java jezik podržava sljedeće vrste komentara.
# 1) Jednoredni komentari: Komentar u jednom retku označen je s „ // ”I kad se sastavljač susretne s njima, ignorira sve što slijedi nakon ovih komentara do kraja retka.
# 2) Višeredni komentari: Višeredni komentari predstavljeni su pomoću ' /*….*/ '. Dakle, prilikom susreta sa slijedom '/ *', sastavljač ignorira sve što slijedi ovaj niz dok ne naiđe na zaključni slijed '* /'.
# 3) Komentari dokumentacije: Oni se nazivaju Doc komentari i alat ih koristi za generiranje API dokumentacije. Komentari dokumenta označeni su kao „ / ** dokumentacija * / '. Kao što vidimo, ti se komentari razlikuju od uobičajenih gore opisanih komentara. Kao što ćemo uskoro vidjeti, komentari dokumenata mogu sadržavati i HTML oznake.
osnovna pitanja i odgovori na intervju za tehničku podršku
Dakle, da bismo generirali API dokumentaciju pomoću ovog alata, moramo pružiti komentare ove dokumentacije (komentare doktora) u našem programu.
Struktura JavaDoc komentara
Struktura dokumenta Doc na Javi slična je višerednom komentaru, osim što komentar dokumenta ima dodatnu zvjezdicu (*) u početnoj oznaci. Dakle, komentar dokumenta započinje s '/ **' umjesto s '/ *'.
Osim toga, komentari u stilu JavaDoc mogu u sebi sadržavati i HTML oznake.
Oblik komentara JavaDoc
Na temelju programske konstrukcije na kojoj želimo dokumentirati, možemo postaviti komentare doktora iznad bilo koje konstrukcije poput klase, metode, polja itd. Prođimo kroz primjere doktora svake konstrukcije.
Format razine razreda
Format komentara dokumenta na razini predavanja izgledat će kako je prikazano u nastavku:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } Kao što je gore prikazano, komentar dokumenta na razini klase sadržavat će sve pojedinosti, uključujući autora klase, veze ako postoje, itd.
Format razine metode
Dolje je dan primjer dokumenta formata na razini metode.
/** * 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; } Kao što vidimo iz gornjeg primjera, u komentaru dokumenta na metodu možemo imati bilo koji broj oznaka. Također možemo imati odlomke unutar opisa komentara označenog s
...
.Također imamo posebne oznake za opis povratne vrijednosti (@return) i parametara metode (@param).
Format razine polja
Sljedeći primjer prikazuje komentar dokumenta za polje.
/** * The public name of a message */ private String msg_txt;Kao što se vidi iz gornjeg primjera, možemo imati i obične komentare bez ikakvih oznaka. Imajte na umu da JavaDoc ne generira nikakvu dokumentaciju za privatna polja, osim ako naredbom JavaDoc ne odredimo privatnu opciju.
Sada razgovarajmo o oznakama koje se koriste s komentarima na dokument.
najbolja besplatna aplikacija za preuzimanje mp3 glazbe za android
JavaDoc oznake
Java nudi razne oznake koje možemo uključiti u komentar dokumenta. Kada koristimo ove oznake, alat raščlanjuje te oznake kako bi iz izvornog koda generirao dobro formatirani API.
Svaka oznaka razlikuje velika i mala slova i započinje znakom '@'. Svaka oznaka započinje na početku retka kao što vidimo iz gornjih primjera. Inače, prevodilac ga tretira kao normalan tekst. Kao dogovor, iste se oznake stavljaju zajedno.
Postoje dvije vrste oznaka koje možemo koristiti u komentaru na dokument.
# 1) Blokiraj oznake : Oznake blokova imaju oblik @tag_name .
Oznake blokova mogu se smjestiti u odjeljak oznaka i slijediti glavni opis .
# 2) Inline oznake :Inline oznake zatvorene su kovrčavim zagradama i oblika su, {@tag_name} . Umetnute oznake mogu se postaviti bilo gdje unutar komentara dokumenta.
Sljedeća tablica navodi sve oznake koje se mogu koristiti u komentarima na dokument.
| Označiti | Opis | Odnosi se na |
|---|---|---|
| @povratak opis | Pruža opis vraćene vrijednosti. | Metoda |
| @autor xyz | Označava autora klase, sučelja ili nabrajanja. | Razred, sučelje, nabrajanje |
| {@docRoot} | Ova oznaka ima relativni put do korijenskog direktorija dokumenta. | Razred, sučelje, nabrajanje, polje, metoda |
| verzija @verzije | Određuje unos verzije softvera. | Razred, sučelje, nabrajanje |
| @ budući da je tekst | Određuje od kada postoji ova funkcija | Razred, sučelje, nabrajanje, polje, metoda |
| @ vidi referencu | Određuje reference (poveznice) na drugu dokumentaciju | Razred, sučelje, nabrajanje, polje, metoda |
| @param opis imena | Koristi se za opis parametra / argumenta metode. | Metoda |
| @exception opis naziva klase | Određuje iznimku koju metoda može unijeti u svoj kod. | Metoda |
| @throws opis naziva klase | ||
| @zaustavljeni opis | Određuje je li metoda zastarjela | Razred, sučelje, nabrajanje, polje, metoda |
| {@inheritDoc} | Koristi se za kopiranje opisa iz nadjačane metode u slučaju nasljeđivanja | Nadjačavanje metode |
| {@link reference} | Pruža reference ili veze na druge simbole. | Razred, sučelje, nabrajanje, polje, metoda |
| {@linkplain reference} | Isto kao i {@link}, ali prikazan je u običnom tekstu. | Razred, sučelje, nabrajanje, polje, metoda |
| {@value #STATIC_FIELD} | Opiši vrijednost statičkog polja. | Statičko polje |
| {@code doslovno} | Koristi se za oblikovanje doslovnog teksta fontom koda sličnim {@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!!'); } } Znamo da ne moramo kompajlirati program ili projekt da bismo generirali JavaDoc. IntelliJIdea Ide nudi ugrađeni alat za generiranje dokumentacije. Slijedite korake u nastavku za generiranje dokumentacije pomoću IntelliJIdee.
- Kliknite Alati -> Generiraj JavaDoc
- Sljedeći se zaslon otvara kada se klikne na alat JavaDoc.
Ovdje možemo odrediti želimo li generirati dokumentaciju za cijeli projekt ili samo za jednu klasu itd. Također možemo odrediti izlazni direktorij u kojem će se generirati datoteke s dokumentacijom. Postoje razne druge specifikacije kao što je prikazano na gornjoj slici.
Kliknite U redu nakon što se navedu svi parametri.
- Sada u prozoru za izlaz možemo vidjeti postupak generiranja Java Doc-a. Primjer izlaznog prozora Java Doc izgleda kako je prikazano dolje:
- Kada se generacija završi, generiraju se sljedeće datoteke.
- Kao što smo naveli klasu Main, generira se datoteka Main.html. Imajte na umu da index.html također ima isti sadržaj kao Main.html.
- Datoteka help-doc.html sadrži opće definicije Java entiteta. Uzorak sadržaja ove datoteke prikazan je u nastavku.
- Slično tome, dolje je dat uzorak sadržaja u datoteci Main.html
Dakle, ovo je način na koji možemo generirati dokumentaciju pomoću ovog alata u ideji IntelliJ. Slične korake možemo slijediti u drugim Java IDE-ima poput Eclipsea i / ili NetBeansa.
Često postavljana pitanja
P # 1) Čemu služi JavaDoc?
Odgovor: JavaDoc alat dolazi s JDK. Koristi se za generiranje dokumentacije koda za Java izvorni kod u HTML formatu. Ovaj alat zahtijeva da se komentari u izvornom kodu daju u unaprijed definiranom formatu kao /**….*/. To se nazivaju i doc komentari.
P # 2) Koji je primjer Java dokumentacije?
Odgovor: Alat za dokumentaciju Java Doc generira HTML datoteke tako da dokumentaciju možemo pregledavati iz web preglednika. Pravi živi primjer JavaDoc dokumentacije je dokumentacija za Java knjižnice u tvrtki Oracle Corporation, http://download.oracle.com/javase/6/ dokumenti /vatra/.
P # 3) Treba li privatnim metodama JavaDoc?
Odgovor: Ne. Privatna polja i metode su samo za programere. Nema logike u pružanju dokumentacije za privatne metode ili polja koja nisu dostupna krajnjem korisniku. Java Doc također ne generira dokumentaciju za privatne entitete.
najbolja aplikacija za izmjenu glasa za računalo
P # 4) Što je JavaDoc naredba?
Odgovor: Ova naredba raščlanjuje deklaracije i komentare dokumenata u izvornim datotekama Java i generira odgovarajuće stranice HTML dokumentacije koje sadrže dokumentaciju za javne i zaštićene klase, ugniježđene klase, konstruktore, metode, polja i sučelja.
Međutim, JavaDoc ne generira dokumentaciju za privatne entitete i anonimne unutarnje klase.
Zaključak
Ovaj je vodič opisao JavaDoc alat pakiran s JDK koji je koristan za generiranje dokumentacije koda za Java izvorni kod u HTML formatu. Dokumentaciju možemo generirati izvršavanjem naredbe Java Doc putem naredbenog alata ili korištenjem ugrađene JavaDoc funkcije dostupne u većini Java IDE-a.
Vidjeli smo kako možemo koristiti alat s IntelliJIdea Java IDE za generiranje dokumentacije. Vodič je također objasnio razne oznake koje se mogu koristiti s komentarima dokumenata, tako da alat može generirati user-friendly dokumentaciju koja detaljno opisuje sve informacije povezane s izvornim kodom.
=> Posjetite ovdje da biste naučili Javu ispočetka.
Preporučena literatura
- Osnove Java: Java sintaksa, Java klasa i osnovni koncepti Java
- Implementacija Jave: Izrada i izvršavanje Java JAR datoteke
- Java virtualni stroj: kako JVM pomaže u pokretanju Java aplikacije
- JAVA Tutorial za početnike: 100+ praktičnih Java Video tutorijala
- Java Integer i Java BigInteger klasa s primjerima
- Java komponente: Java platforma, JDK, JRE i Java virtualni stroj
- Kako stvoriti API dokumentaciju u poštaru?