what is javadoc how use it generate documentation
V tomto výučbe sa dozviete, čo sú nástroj JavaDoc a poznámky a postupy JavaDoc na generovanie dokumentácie kódu:
JavaDoc je špeciálny nástroj, ktorý je súčasťou balíka JDK. Používa sa na generovanie dokumentácie kódu zdrojového kódu Java vo formáte HTML.
Jedná sa o generátor dokumentácie pre jazyk Java od spoločnosti Sun Microsystems (v súčasnosti Oracle Corporation).
=> Skontrolujte VŠETKY návody Java tu.
Čo sa dozviete:
Čo je JavaDoc
Tento nástroj používa na dokumentovanie tried Java formát „komentáre k dokladu“. IDE ako Eclipse, IntelliJIDEA alebo NetBeans majú zabudovaný nástroj JavaDoc na generovanie dokumentácie HTML. Na trhu máme tiež veľa editorov súborov, ktoré programátorovi môžu pomôcť pri produkcii zdrojov JavaDoc.
Okrem dokumentácie zdrojového kódu poskytuje tento nástroj aj API, ktoré vytvára „doclets“ a „taglets“, ktoré používame na analýzu štruktúry Java aplikácie.
Je potrebné poznamenať, že tento nástroj nijako neovplyvňuje výkon aplikácie, pretože kompilátor odstráni všetky poznámky počas kompilácie programu Java.
Písanie komentárov do programu a následné použitie JavaDoc na vygenerovanie dokumentácie má pomôcť programátorovi / používateľovi porozumieť kódu.
Dokumentácia HTML generovaná programom JavaDoc je dokumentácia API. Analyzuje vyhlásenia a generuje množinu zdrojových súborov. Zdrojový súbor popisuje polia, metódy, konštruktory a triedy.
Upozorňujeme, že predtým, ako na svojom zdrojovom kóde použijeme nástroj JavaDoc, musíme do programu zahrnúť špeciálne komentáre JavaDoc.
Prejdime teraz k komentárom.
Komentáre JavaDoc
Jazyk Java podporuje nasledujúce typy komentárov.
# 1) Komentáre k jednému riadku: Jednoriadkový komentár je označený „ // ”A keď sa s nimi kompilátor stretne, do konca riadku ignoruje všetko, čo nasleduje po týchto komentároch.
# 2) Viacriadkové komentáre: Viacriadkové komentáre sú zobrazené pomocou „ /*….*/ “. Takže keď narazí na postupnosť „/ *“, kompilátor ignoruje všetko, čo nasleduje po tejto postupnosti, kým nenarazí na koncovú postupnosť „* /“.
# 3) Komentáre k dokumentácii: Nazývajú sa komentáre k dokumentu a nástroj ich používa na generovanie dokumentácie API. Komentáre k dokumentu sú označené ako „ / ** dokumentácia * / “. Ako vidíme, tieto komentáre sa líšia od bežných komentárov opísaných vyššie. Komentáre k dokumentom môžu obsahovať aj HTML značky, ako uvidíme čoskoro.
ako pridať úložisko svn v zatmení -
Aby sme teda pomocou tohto nástroja mohli vygenerovať dokumentáciu API, musíme v našom programe poskytnúť tieto komentáre k dokumentácii (komentáre k dokumentom).
Štruktúra komentára JavaDoc
Štruktúra komentára Doc v Jave je podobná viacriadkovému komentáru, až na to, že komentár k dokladu má v úvodnej značke ďalšiu hviezdičku (*). Komentár k dokumentu teda začína na „/ **“ namiesto na / / *.
Komentáre v štýle JavaDoc môžu navyše obsahovať aj značky HTML.
Formát komentára JavaDoc
Na základe programovacieho konštruktu, ktorý chceme dokumentovať, môžeme umiestniť komentáre k dokumentom nad akýkoľvek konštrukt, ako je trieda, metóda, pole atď. Poďme si predstaviť príklady všetkých komentárov k dokladu konštruktov.
Formát na úrovni triedy
Formát komentára k dokumentu na úrovni triedy bude vyzerať nasledovne:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods }
Ako je uvedené vyššie, komentár k dokumentu na úrovni triedy bude obsahovať všetky podrobnosti vrátane autora triedy, odkazy, ak existujú, atď.
Formát úrovne metódy
Ďalej je uvedený príklad formátu doc na úrovni metódy.
/** * 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; }
Ako vidíme z vyššie uvedeného príkladu, v komentári k metóde môžeme mať ľubovoľný počet značiek. Odseky vnútri popisu komentára môžu byť označené symbolom
...
.Máme tiež špeciálne značky na popis návratovej hodnoty (@return) a parametrov metódy (@param).
Formát na úrovni poľa
Nasledujúci príklad zobrazuje komentár k poli pre pole.
/** * The public name of a message */ private String msg_txt;
Ako je zrejmé z vyššie uvedeného príkladu, môžeme mať aj obyčajné komentáre bez akýchkoľvek značiek. Upozorňujeme, že JavaDoc negeneruje žiadnu dokumentáciu pre súkromné polia, pokiaľ neurčíme príkaz private pomocou príkazu JavaDoc.
Teraz si predstavíme značky, ktoré sa používajú v komentároch k dokumentu.
Značky JavaDoc
Java poskytuje rôzne značky, ktoré môžeme zahrnúť do komentára k dokumentu. Keď tieto značky použijeme, nástroj tieto značky analyzuje a vygeneruje zo zdrojového kódu dobre naformátované rozhranie API.
Každá značka rozlišuje veľké a malé písmená a začína znakom „@“. Každá značka začína na začiatku riadku, ako vidíme z vyššie uvedených príkladov. Inak to kompilátor považuje za normálny text. Na základe konvencie sú rovnaké značky umiestnené spolu.
V komentári k dokumentu môžeme použiť dva typy značiek.
# 1) Blokovať značky : Blokové značky majú formu @tag_name .
Blokové značky je možné umiestniť do sekcie značiek a postupovať podľa hlavného popisu .
# 2) Vložené značky :Vložené riadky sú uzavreté v zložených zátvorkách a majú tvar, {@tag_name} . Vložené riadky je možné umiestniť kdekoľvek vo vnútri komentára k dokumentu.
V nasledujúcej tabuľke je uvedený zoznam všetkých značiek, ktoré je možné použiť v komentároch k dokumentu.
Označiť | Popis | Týka sa |
---|---|---|
@ návratový popis | Poskytuje popis návratovej hodnoty. | Metóda |
@autor xyz | Označuje autora triedy, rozhrania alebo výčtu. | Trieda, rozhranie, výčet |
{@docRoot} | Táto značka má relatívnu cestu ku koreňovému adresáru dokumentu. | Trieda, rozhranie, výčet, pole, metóda |
verzia @verzia | Určuje zadanie verzie softvéru. | Trieda, rozhranie, výčet |
@ keďže od-textu | Určuje, odkedy táto funkcia existuje | Trieda, rozhranie, výčet, pole, metóda |
@ pozri referenciu | Určuje odkazy (odkazy) na inú dokumentáciu | Trieda, rozhranie, výčet, pole, metóda |
Popis názvu @param | Používa sa na popísanie parametra / argumentu metódy. | Metóda |
popis @výnimky triedy | Určuje výnimku, ktorú môže metóda vložiť do svojho kódu. | Metóda |
@hodí popis názvu triedy | ||
@ zastaraný popis | Určuje, či je metóda zastaraná | Trieda, rozhranie, výčet, pole, metóda |
{@inheritDoc} | Používa sa na kopírovanie popisu z prepísanej metódy v prípade dedenia | Prvoradá metóda |
{@link reference} | Poskytuje odkazy alebo odkazy na iné symboly. | Trieda, rozhranie, výčet, pole, metóda |
{@linkplain reference} | Rovnaké ako {@link}, ale zobrazuje sa ako obyčajný text. | Trieda, rozhranie, výčet, pole, metóda |
{@value #STATIC_FIELD} | Popíšte hodnotu statického poľa. | Statické pole |
{@code literal} | Používa sa na formátovanie doslovného textu v písme kódu podobnom {@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.
bezplatný softvér na obnovu dát Windows 10
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!!'); } }
Vieme, že na generovanie JavaDoc nepotrebujeme program alebo projekt kompilovať. IntelliJIdea Ide poskytuje zabudovaný nástroj na generovanie dokumentácie. Podľa nasledujúcich pokynov vygenerujte dokumentáciu pomocou programu IntelliJIdea.
- Kliknite na Nástroje -> Generovať JavaDoc
- Po kliknutí na nástroj JavaDoc sa otvorí nasledujúca obrazovka.
Tu môžeme určiť, či chceme generovať dokumentáciu pre celý projekt alebo iba pre jednu triedu atď. Môžeme tiež určiť výstupný adresár, kde sa budú generovať súbory dokumentácie. Existuje mnoho ďalších špecifikácií, ktoré sú znázornené na obrázku vyššie.
Po zadaní všetkých parametrov kliknite na OK.
- Teraz môžeme vo výstupnom okne vidieť proces generovania Java Doc. Vzorové výstupné okno Java Doc vyzerá takto:
- Po dokončení generovania sa vygenerujú nasledujúce súbory.
- Ako sme určili triedu Main, vygeneruje sa súbor Main.html. Upozorňujeme, že index.html má tiež rovnaký obsah ako Main.html.
- Súbor help-doc.html obsahuje všeobecné definície entít Java. Ukážka obsahu tohto súboru je uvedená nižšie.
- Podobne je uvedený nižšie ukážkový obsah v súbore Main.html
Týmto spôsobom teda môžeme generovať dokumentáciu pomocou tohto nástroja v nápade IntelliJ. Podobné kroky môžeme postupovať aj v iných IDE Java, ako napríklad Eclipse a / alebo NetBeans.
často kladené otázky
Otázka 1) Na čo slúži program JavaDoc?
Odpoveď: Nástroj JavaDoc sa dodáva s JDK. Používa sa na generovanie dokumentácie kódu pre zdrojový kód Java vo formáte HTML. Tento nástroj vyžaduje, aby boli komentáre v zdrojovom kóde poskytované v preddefinovanom formáte ako /**….*/. Nazývajú sa tiež doc comments.
Otázka 2) Aký je príklad dokumentácie Java?
Odpoveď: Dokumentačný nástroj Java Doc generuje súbory HTML, aby sme mohli dokumentáciu prezerať z webového prehliadača. Skutočným živým príkladom dokumentácie JavaDoc je dokumentácia pre knižnice Java v spoločnosti Oracle Corporation, http://download.oracle.com/javase/6/ doc / oheň /.
Otázka č. 3) Vyžadujú súkromné metódy JavaDoc?
Odpoveď: Nie. Súkromné polia a metódy sú iba pre vývojárov. Poskytovanie dokumentácie pre súkromné metódy alebo polia, ktoré nie sú prístupné koncovému používateľovi, nemá logiku. Java Doc taktiež negeneruje dokumentáciu pre súkromné subjekty.
spoločnosti, kde pracujú s videohrami
Otázka č. 4) Čo je príkaz JavaDoc?
Odpoveď: Tento príkaz analyzuje vyhlásenia a komentáre k dokumentom v zdrojových súboroch Java a generuje zodpovedajúce stránky dokumentácie HTML, ktoré obsahujú dokumentáciu pre verejné a chránené triedy, vnorené triedy, konštruktory, metódy, polia a rozhrania.
JavaDoc však negeneruje dokumentáciu pre súkromné entity a anonymné vnútorné triedy.
Záver
Tento výukový program popísal nástroj JavaDoc zabalený s JDK, ktorý je užitočný na generovanie dokumentácie kódu pre zdrojový kód Java vo formáte HTML. Dokumentáciu môžeme vytvoriť buď vykonaním príkazu Java Doc pomocou príkazového nástroja, alebo pomocou zabudovanej funkcie JavaDoc dostupnej vo väčšine IDE Java.
Videli sme, ako môžeme nástroj použiť na IntelliJIdea Java IDE na generovanie dokumentácie. Výukový program tiež vysvetlil rôzne značky, ktoré je možné použiť pri komentároch k dokumentom, aby nástroj mohol generovať užívateľsky príjemnú dokumentáciu s podrobnými informáciami o zdrojovom kóde.
=> Navštívte tu a dozviete sa Java od začiatku.
Odporúčané čítanie
- Základy jazyka Java: Java Syntax, trieda Java a základné koncepty Java
- Nasadenie Java: Vytvorenie a vykonanie súboru Java JAR
- Virtuálny stroj Java: Ako JVM pomáha pri spúšťaní aplikácií Java
- Výukový program JAVA pre začiatočníkov: viac ako 100 praktických výučbových programov Java Video
- Celé číslo Java a trieda Java BigInteger s príkladmi
- Komponenty Java: Java Platform, JDK, JRE a Java Virtual Machine
- Ako vytvoriť dokumentáciu API v službe Postman?