what is javadoc how use it generate documentation
Ta vadnica razlaga, kaj so orodje JavaDoc in komentarji in metode JavaDoc za ustvarjanje dokumentacije kode:
JavaDoc je posebno orodje, ki je priloženo JDK. Uporablja se za ustvarjanje dokumentacije kode izvorne kode Java v obliki HTML.
Je generator dokumentacije za jezik Java podjetja Sun Microsystems (trenutno Oracle Corporation).
=> Tukaj preverite VSE Vadnice za Java.
Kaj se boste naučili:
Kaj je JavaDoc
To orodje uporablja zapis »doc comments« za dokumentiranje razredov Java. IDE, kot so Eclipse, IntelliJIDEA ali NetBeans, imajo vgrajeno orodje JavaDoc za ustvarjanje dokumentacije HTML. Na trgu imamo tudi veliko urejevalnikov datotek, ki lahko programerju pomagajo pri izdelavi virov JavaDoc.
Poleg dokumentacije izvorne kode to orodje ponuja tudi API, ki ustvarja 'doclets' in 'taglets', ki jih uporabljamo za analizo strukture aplikacije Java.
Treba je omeniti, da to orodje na noben način ne vpliva na delovanje aplikacije, saj prevajalnik med prevajanjem programa Java odstrani vse komentarje.
Pisanje komentarjev v program in nato uporaba JavaDoc za ustvarjanje dokumentacije je v pomoč programerju / uporabniku, da razume kodo.
Dokumentacija HTML, ki jo ustvari JavaDoc, je dokumentacija API. Razčleni deklaracije in ustvari nabor izvornih datotek. Izvorna datoteka opisuje polja, metode, konstruktorje in razrede.
Preden uporabimo orodje JavaDoc v izvorni kodi, moramo v program vključiti posebne komentarje JavaDoc.
Pojdimo zdaj k komentarjem.
Komentarji JavaDoc
Jezik Java podpira naslednje vrste komentarjev.
# 1) Enovrstični komentarji: Enovrstični komentar je označen z „ // 'In ko prevajalnik naleti nanje, prezre vse, kar sledi tem komentarjem, do konca vrstice.
# 2) Komentarji z več vrsticami: Večvrstni komentarji so predstavljeni s pomočjo /*….*/ '. Torej, ko naleti na zaporedje '/ *', prevajalnik prezre vse, kar sledi temu zaporedju, dokler ne naleti na zaključno zaporedje '* /'.
# 3) Komentarji dokumentacije: Ti se imenujejo komentarji dokumenta in jih orodje uporablja za ustvarjanje dokumentacije API. Komentarji dokumenta so označeni kot „ / ** dokumentacija * / '. Kot vidimo, se ti komentarji razlikujejo od običajnih zgoraj opisanih komentarjev. Kot bomo kmalu videli, lahko komentarji dokumenta vsebujejo tudi oznake HTML.
vprašanja o oracle pl sql intervjuju in odgovori za izkušene pdf
Torej, če želimo s pomočjo tega orodja ustvariti dokumentacijo API, moramo v naš program vključiti te komentarje dokumentacije (komentarje dokumenta).
Struktura komentarja JavaDoc
Struktura komentarja dokumenta v Javi je podobna komentarju z več vrsticami, le da ima komentar dokumenta v uvodni oznaki dodatno zvezdico (*). Komentar dokumenta se torej začne z '/ **' namesto z '/ *'.
Poleg tega lahko komentarji v slogu JavaDoc vsebujejo tudi oznake HTML.
Oblika komentarja JavaDoc
Na podlagi programske konstrukcije, na kateri želimo dokumentirati, lahko postavimo komentarje dokumenta nad kateri koli konstrukt, kot je razred, metoda, polje itd. Poglejmo si primere komentarjev dokumenta vsakega konstrukta.
Oblika na ravni razreda
Format komentarja dokumenta na ravni predavanj bo videti tako, kot je prikazano spodaj:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } Kot je prikazano zgoraj, bo komentar dokumenta na ravni razreda vseboval vse podrobnosti, vključno z avtorjem predavanja, morebitnimi povezavami itd.
Oblika ravni metode
Spodaj je primer oblike dokumenta na ravni 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; } Kot lahko vidimo iz zgornjega primera, imamo lahko v komentarju dokumenta metodo poljubno število oznak. V opisu komentarja, ki ga označuje, lahko imamo tudi odstavke
...
.Imamo tudi posebne oznake za opis vrnjene vrednosti (@return) in parametrov metode (@param).
orodje za popravilo programske opreme za Windows 10
Oblika ravni polja
Naslednji primer prikazuje komentar dokumenta za polje.
/** * The public name of a message */ private String msg_txt;Kot je razvidno iz zgornjega primera, imamo lahko tudi navadne komentarje brez oznak. Upoštevajte, da JavaDoc ne ustvarja nobene dokumentacije za zasebna polja, razen če z ukazom JavaDoc določimo zasebno možnost.
Zdaj pa se pogovorimo o oznakah, ki se uporabljajo s komentarji dokumenta.
Oznake JavaDoc
Java ponuja različne oznake, ki jih lahko vključimo v komentar o dokumentu. Ko uporabimo te oznake, orodje te oznake razčleni, da iz izvorne kode ustvari dobro formatiran API.
Vsaka oznaka razlikuje med velikimi in malimi črkami in se začne z znakom „@“. Vsaka oznaka se začne na začetku vrstice, kot lahko vidimo iz zgornjih primerov. Sicer ga prevajalnik obravnava kot običajno besedilo. Po dogovoru so iste oznake postavljene skupaj.
V komentarju dokumenta lahko uporabimo dve vrsti oznak.
# 1) Blokiraj oznake : Oznake blokov imajo obliko @tag_name .
Blokirane oznake lahko postavite v razdelek z oznakami in sledite glavnemu opisu .
# 2) Vstavljene oznake :Vstavljene oznake so zavite v zavite oklepaje in so v obliki, {@tag_name} . Vstavljene oznake lahko postavite kjer koli znotraj komentarja dokumenta.
V naslednji tabeli so navedene vse oznake, ki jih je mogoče uporabiti v komentarjih dokumenta.
| Oznaka | Opis | Velja za |
|---|---|---|
| @ vrnitev opis | Ponuja opis vrnjene vrednosti. | Metoda |
| @avtor xyz | Označuje avtorja razreda, vmesnika ali naštevanja. | Razred, vmesnik, enum |
| {@docRoot} | Ta oznaka ima relativno pot do korenskega imenika dokumenta. | Razred, vmesnik, enum, polje, metoda |
| različica @version | Določa vnos različice programske opreme. | Razred, vmesnik, enum |
| @ odkar je besedilo | Določa, od kdaj ta funkcionalnost obstaja | Razred, vmesnik, enum, polje, metoda |
| @ glej referenco | Določa sklice (povezave) na drugo dokumentacijo | Razred, vmesnik, enum, polje, metoda |
| Opis imena @param | Uporablja se za opis parametra / argumenta metode. | Metoda |
| Opis imena @exception classname | Določa izjemo, ki jo metoda lahko vrže v svojo kodo. | Metoda |
| Opis imena razreda @throws | ||
| @ zastarel opis | Določa, ali je metoda zastarela | Razred, vmesnik, enum, polje, metoda |
| {@inheritDoc} | Uporablja se za kopiranje opisa iz razveljavljene metode v primeru dedovanja | Preglasitev metode |
| {@link reference} | Ponuja sklice ali povezave do drugih simbolov. | Razred, vmesnik, enum, polje, metoda |
| {@linkplain reference} | Enako kot {@link}, vendar je prikazano v navadnem besedilu. | Razred, vmesnik, enum, polje, metoda |
| {@value #STATIC_FIELD} | Opišite vrednost statičnega polja. | Statično polje |
| {@code literal} | Uporablja se za oblikovanje dobesednega besedila v pisavi kode, podobno kot {@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!!'); } } Vemo, da nam za ustvarjanje JavaDoc ni treba prevajati programa ali projekta. IntelliJIdea Ide ponuja vgrajeno orodje za ustvarjanje dokumentacije. Sledite spodnjim korakom, da ustvarite dokumentacijo z uporabo IntelliJIdea.
- Kliknite Orodja -> Ustvari JavaDoc
- Ko kliknete orodje JavaDoc, se odpre naslednji zaslon.
Tu lahko določimo, ali želimo ustvariti dokumentacijo za celoten projekt ali samo za en razred itd. Določimo lahko tudi izhodni imenik, v katerem bodo ustvarjene datoteke z dokumentacijo. Obstajajo različne druge specifikacije, kot je prikazano na zgornji sliki.
Ko so navedeni vsi parametri, kliknite V redu.
- Zdaj lahko v izhodnem oknu vidimo postopek ustvarjanja Java Doc. Vzorec izhodnega okna Java Doc je videti, kot je prikazano spodaj:
- Ko se generacija konča, se ustvarijo naslednje datoteke.
- Kot smo določili razred Main, se ustvari datoteka Main.html. Upoštevajte, da ima index.html tudi enako vsebino kot Main.html.
- Datoteka help-doc.html vsebuje splošne definicije entitet Java. Vzorec vsebine te datoteke je prikazan spodaj.
- Podobno je spodaj naveden vzorec vsebine v datoteki Main.html
Tako lahko na ta način ustvarimo dokumentacijo s pomočjo tega orodja v zamisli IntelliJ. Podobne korake lahko sledimo tudi v drugih Java IDE, kot sta Eclipse in / ali NetBeans.
Pogosto zastavljena vprašanja
V # 1) Za kaj se uporablja JavaDoc?
Odgovor: Orodje JavaDoc je priloženo JDK. Uporablja se za ustvarjanje dokumentacije kode za izvorno kodo Java v obliki HTML. To orodje zahteva, da so komentarji v izvorni kodi navedeni v vnaprej določeni obliki zapisa /**….*/. Temu pravimo tudi doc komentarji.
V # 2) Kakšen je primer dokumentacije Java?
Odgovor: Orodje za dokumentacijo Java Doc ustvari datoteke HTML, da si lahko dokumentacijo ogledamo iz spletnega brskalnika. Pravi primer dokumentacije JavaDoc v živo je dokumentacija za knjižnice Java v podjetju Oracle Corporation, http://download.oracle.com/javase/6/ dokumenti / ogenj /.
V # 3) Ali zasebne metode potrebujejo JavaDoc?
Odgovor: Ne. Zasebna polja in metode so samo za razvijalce. Ni logike pri zagotavljanju dokumentacije za zasebne metode ali polja, ki niso dostopna končnemu uporabniku. Java Doc tudi ne ustvarja dokumentacije za zasebne entitete.
orodja, ki jih poslovni analitik uporablja za zbiranje potreb
V # 4) Kaj je ukaz JavaDoc?
Odgovor: Ta ukaz razčleni izjave in komentarje dokumentov v izvornih datotekah Java in ustvari ustrezne strani dokumentacije HTML, ki vsebujejo dokumentacijo za javne in zaščitene razrede, ugnezdene razrede, konstruktorje, metode, polja in vmesnike.
Vendar JavaDoc ne ustvarja dokumentacije za zasebne entitete in anonimne notranje razrede.
Zaključek
V tej vadnici je opisano orodje JavaDoc, pakirano z JDK, ki je uporabno za ustvarjanje dokumentacije kode za izvorno kodo Java v obliki HTML. Dokumentacijo lahko ustvarimo bodisi z izvajanjem ukaza Java Doc prek ukaznega orodja bodisi z uporabo vgrajene funkcije JavaDoc, ki je na voljo v večini IDE Java.
Videli smo, kako lahko orodje z IntelliJIdea Java IDE uporabimo za ustvarjanje dokumentacije. Vadnica je razložila tudi različne oznake, ki jih je mogoče uporabiti s komentarji dokumentov, tako da lahko orodje ustvari uporabniku prijazno dokumentacijo s podrobnostmi o vseh informacijah v zvezi z izvorno kodo.
=> Obiščite tukaj, če se želite naučiti Jave iz nič.
Priporočeno branje
- Osnove Java: Sintaksa Java, Razred Java in Osnovni koncepti Java
- Uvajanje Java: Ustvarjanje in izvajanje datoteke Java JAR
- Navidezni stroj Java: kako JVM pomaga pri zagonu aplikacije Java
- JAVA Vadnica za začetnike: 100+ praktičnih Javnih video vadnic
- Java Integer in Java BigInteger Class z primeri
- Komponente Java: Java Platform, JDK, JRE in Java Virtual Machine
- Kako ustvariti dokumentacijo API v poštarju?