what is javadoc how use it generate documentation
Tento výukový program vysvětluje, co jsou nástroj JavaDoc a poznámky a metody JavaDoc ke generování dokumentace kódu:
JavaDoc je speciální nástroj, který je součástí balíku JDK. Používá se ke generování kódové dokumentace zdrojového kódu Java ve formátu HTML.
Jedná se o generátor dokumentace pro jazyk Java od společnosti Sun Microsystems (v současnosti Oracle Corporation).
=> Zkontrolujte VŠECHNY výukové programy Java zde.
Co se naučíte:
Co je JavaDoc
Tento nástroj používá k dokumentování tříd Java formát „komentáře k dokumentu“. IDE jako Eclipse, IntelliJIDEA nebo NetBeans mají zabudovaný nástroj JavaDoc pro generování dokumentace HTML. Na trhu máme také mnoho editorů souborů, které mohou programátorovi pomoci s produkcí zdrojů JavaDoc.
Kromě dokumentace zdrojového kódu poskytuje tento nástroj také API, které vytváří „doclety“ a „taglety“, které používáme k analýze struktury Java aplikace.
Je třeba poznamenat, že tento nástroj žádným způsobem neovlivňuje výkon aplikace, protože kompilátor odstraní všechny komentáře během kompilace programu Java.
Psaní komentářů v programu a následné použití JavaDoc ke generování dokumentace má pomoci programátorovi / uživateli porozumět kódu.
Dokumentace HTML generovaná programem JavaDoc je dokumentace API. Analyzuje deklarace a generuje sadu zdrojových souborů. Zdrojový soubor popisuje pole, metody, konstruktory a třídy.
Před použitím nástroje JavaDoc v našem zdrojovém kódu musíme do programu zahrnout speciální komentáře JavaDoc.
Pojďme nyní k komentářům.
Komentáře JavaDoc
Jazyk Java podporuje následující typy komentářů.
# 1) Jednořádkové komentáře: Jednořádkový komentář je označen „ // „A když na ně překladač narazí, ignoruje vše, co následuje po těchto komentářích, až do konce řádku.
# 2) Víceřádkové komentáře: Víceřádkové komentáře jsou reprezentovány pomocí „ /*….*/ “. Takže když narazí na posloupnost „/ *“, kompilátor ignoruje vše, co následuje po této posloupnosti, dokud nenarazí na uzavírací posloupnost „* /“.
# 3) Komentáře k dokumentaci: Tito se nazývají Doc comments a jsou používány nástrojem ke generování dokumentace API. Komentáře dokumentu jsou označeny jako „ / ** dokumentace * / “. Jak vidíme, tyto komentáře se liší od běžných komentářů popsaných výše. Komentáře dokumentu mohou také obsahovat HTML tagy, jak uvidíme brzy.
Software pro kopírování a vypalování DVD zdarma
Abychom mohli pomocí tohoto nástroje generovat dokumentaci API, musíme v našem programu poskytnout tyto komentáře k dokumentům (komentáře k dokumentům).
Struktura komentáře JavaDoc
Struktura komentáře Doc v Javě je podobná víceřádkovému komentáři, kromě toho, že komentář komentáře má v úvodní značce další hvězdičku (*). Komentář dokumentu tedy začíná na „/ **“ místo na „/ *“.
Komentáře stylu JavaDoc mohou navíc obsahovat také značky HTML.
Formát komentářů JavaDoc
Na základě programovacího konstruktu, který chceme dokumentovat, můžeme umístit komentáře k dokumentu nad jakýkoli konstrukt, jako je třída, metoda, pole atd. Pojďme si projít příklady každého z komentářů k konstruktům.
Formát na úrovni třídy
Formát komentářů k dokumentu na úrovni třídy bude vypadat takto:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods }
Jak je uvedeno výše, komentář k dokumentu na úrovni třídy bude obsahovat všechny podrobnosti, včetně autora třídy, odkazy, pokud existují, atd.
Formát úrovně metody
Níže je uveden příklad formátu doc na úrovni metody.
/** * 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; }
Jak vidíme z výše uvedeného příkladu, můžeme mít v komentáři k dokumentu libovolný počet značek. Můžeme mít také odstavce uvnitř popisu komentáře označené
...
jak otevírat soubory .eps.
Máme také speciální značky, které popisují návratovou hodnotu (@return) a parametry metody (@param).
Formát na úrovni pole
Následující příklad ukazuje komentář k poli pro pole.
/** * The public name of a message */ private String msg_txt;
Jak je vidět z výše uvedeného příkladu, můžeme mít také prosté komentáře bez jakýchkoli značek. Všimněte si, že JavaDoc negeneruje žádnou dokumentaci pro soukromá pole, pokud pomocí příkazu JavaDoc nezadáme soukromou možnost.
Nyní pojďme diskutovat o značkách použitých s komentáři k dokumentu.
Značky JavaDoc
Java poskytuje různé značky, které můžeme zahrnout do komentáře k dokumentu. Když tyto značky použijeme, nástroj tyto značky analyzuje a vygeneruje ze zdrojového kódu dobře formátované rozhraní API.
Každá značka rozlišuje velká a malá písmena a začíná znakem „@“. Jak vidíme z výše uvedených příkladů, každá značka začíná na začátku řádku. Jinak to kompilátor považuje za normální text. Jako konvence jsou stejné značky umístěny společně.
V komentáři k dokumentu můžeme použít dva typy značek.
# 1) Blokovat značky : Blokové značky mají formu @název štítku .
Značky bloků lze umístit do sekce značek a postupovat podle hlavního popisu .
# 2) Vložené značky :Řádkové značky jsou uzavřeny do složených závorek a mají tvar, {@název štítku} . Vložené značky lze umístit kdekoli uvnitř komentáře k dokumentu.
V následující tabulce jsou uvedeny všechny značky, které lze použít v komentářích k dokumentu.
Štítek | Popis | Platí pro |
---|---|---|
popis @return | Poskytuje popis návratové hodnoty. | Metoda |
@autor xyz | Určuje autora třídy, rozhraní nebo výčtu. | Třída, rozhraní, výčet |
{@docRoot} | Tato značka má relativní cestu ke kořenovému adresáři dokumentu. | Třída, rozhraní, výčet, pole, metoda |
@ verze verze | Určuje zadání verze softwaru. | Třída, rozhraní, výčet |
@ od té doby od textu | Určuje, od kdy tato funkce existuje | Třída, rozhraní, výčet, pole, metoda |
@ viz odkaz | Určuje odkazy (odkazy) na další dokumentaci | Třída, rozhraní, výčet, pole, metoda |
Popis názvu @param | Používá se k popisu parametru / argumentu metody. | Metoda |
@výjimka popis třídy | Určuje výjimku, kterou může metoda vložit do svého kódu. | Metoda |
@hodí popis názvu třídy | ||
@ zastaralý popis | Určuje, zda je metoda zastaralá | Třída, rozhraní, výčet, pole, metoda |
{@inheritDoc} | Slouží ke kopírování popisu z přepsané metody v případě dědičnosti | Prvořadá metoda |
{@link reference} | Poskytuje odkazy nebo odkazy na jiné symboly. | Třída, rozhraní, výčet, pole, metoda |
{@linkplain reference} | Stejné jako {@link}, ale zobrazuje se jako prostý text. | Třída, rozhraní, výčet, pole, metoda |
{@value #STATIC_FIELD} | Popište hodnotu statického pole. | Statické pole |
{@code literal} | Používá se k formátování doslovného textu v písmu kódu podobném {@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!!'); } }
Víme, že pro generování JavaDoc program nebo projekt nepotřebujeme kompilovat. IntelliJIdea Ide poskytuje vestavěný nástroj pro generování dokumentace. Podle níže uvedených kroků vygenerujte dokumentaci pomocí IntelliJIdea.
- Klikněte na Nástroje -> Generovat JavaDoc
- Po klepnutí na nástroj JavaDoc se otevře následující obrazovka.
Zde můžeme určit, zda chceme generovat dokumentaci pro celý projekt nebo pouze pro jednu třídu atd. Můžeme také určit výstupní adresář, kde budou generovány soubory dokumentace. Na obrázku výše je uvedeno několik dalších specifikací.
Jakmile jsou zadány všechny parametry, klikněte na OK.
- Nyní můžeme vidět výstupní proces Java Doc ve výstupním okně. Ukázkové výstupní okno Java Doc vypadá takto:
- Po dokončení generování se vygenerují následující soubory.
- Jak jsme určili třídu Main, vygeneruje se soubor Main.html. Všimněte si, že index.html má také stejný obsah jako Main.html.
- Soubor help-doc.html obsahuje obecné definice entit Java. Níže je uveden ukázkový obsah tohoto souboru.
- Podobně je uveden níže ukázkový obsah v souboru Main.html
To je tedy způsob, jakým můžeme generovat dokumentaci pomocí tohoto nástroje v IntelliJ idea. Můžeme postupovat podobnými kroky v jiných prostředích Java IDE, jako je Eclipse a / nebo NetBeans.
Často kladené otázky
Otázka č. 1) Jaké je použití JavaDoc?
Odpovědět: Nástroj JavaDoc je dodáván s JDK. Používá se ke generování dokumentace kódu pro zdrojový kód Java ve formátu HTML. Tento nástroj vyžaduje, aby byly komentáře ve zdrojovém kódu poskytovány v předdefinovaném formátu jako /**….*/. Také se nazývají komentáře k dokumentům.
Otázka 2) Co je příklad dokumentace Java?
Odpovědět: Dokumentační nástroj Java Doc generuje soubory HTML, abychom mohli dokumentaci prohlížet z webového prohlížeče. Skutečným živým příkladem dokumentace JavaDoc je dokumentace pro knihovny Java v Oracle Corporation, http://download.oracle.com/javase/6/ dokumenty /oheň/.
Otázka č. 3) Potřebují soukromé metody JavaDoc?
Odpovědět: Ne. Soukromá pole a metody jsou pouze pro vývojáře. Poskytování dokumentace pro soukromé metody nebo pole, která nejsou přístupná koncovému uživateli, nemá logiku. Java Doc také negeneruje dokumentaci pro soukromé subjekty.
zdarma DVD Ripper pro Windows 7
Otázka č. 4) Co je příkaz JavaDoc?
Odpovědět: Tento příkaz analyzuje deklarace a komentáře k dokumentům ve zdrojových souborech Java a generuje odpovídající stránky dokumentace HTML obsahující dokumentaci pro veřejné a chráněné třídy, vnořené třídy, konstruktory, metody, pole a rozhraní.
JavaDoc však negeneruje dokumentaci pro soukromé entity a anonymní vnitřní třídy.
Závěr
Tento kurz popsal nástroj JavaDoc zabalený s JDK, který je užitečný pro generování dokumentace kódu pro zdrojový kód Java ve formátu HTML. Můžeme generovat dokumentaci buď spuštěním příkazu Java Doc pomocí příkazového nástroje, nebo pomocí vestavěné funkce JavaDoc dostupné ve většině prostředí Java IDE.
Viděli jsme, jak můžeme nástroj použít s IntelliJIdea Java IDE ke generování dokumentace. Výukový program také vysvětlil různé značky, které lze použít s komentáři k dokumentu, aby nástroj mohl generovat uživatelsky přívětivou dokumentaci s podrobnými informacemi o zdrojovém kódu.
=> Navštivte zde a dozvíte se Java od začátku.
Doporučené čtení
- Základy jazyka Java: Syntaxe jazyka Java, třída Java a základní koncepty Java
- Implementace Java: Vytvoření a spuštění souboru Java JAR
- Virtuální stroj Java: Jak JVM pomáhá při spouštění aplikace Java
- Výukový program JAVA pro začátečníky: 100+ praktických výukových programů Java Video
- Celé číslo Java a třída Java BigInteger s příklady
- Komponenty Java: Platforma Java, JDK, JRE a Java Virtual Machine
- Jak vytvořit dokumentaci API v Postmanu?