Menu

Co je JavaDoc a jak jej používat k vytváření dokumentace

  • Hlavní
  • Jiný
  • Co je JavaDoc a jak jej používat k vytváření dokumentace

what is javadoc how use it generate documentation

Vyzkoušejte Náš Nástroj Pro Odstranění Problémů

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.

Nástroj JavaDoc

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ítekPopisPlatí pro
popis @returnPoskytuje popis návratové hodnoty.Metoda
@autor xyzUrč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 verzeUrčuje zadání verze softwaru.Třída, rozhraní, výčet
@ od té doby od textuUrčuje, od kdy tato funkce existujeTřída, rozhraní, výčet, pole, metoda
@ viz odkazUrčuje odkazy (odkazy) na další dokumentaciTřída, rozhraní, výčet, pole, metoda
Popis názvu @paramPoužívá se k popisu parametru / argumentu metody.Metoda
@výjimka popis třídyUrčuje výjimku, kterou může metoda vložit do svého kódu.Metoda
@hodí popis názvu třídy
@ zastaralý popisUrč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čnostiPrvoř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

Generovat JavaDoc

  • Po klepnutí na nástroj JavaDoc se otevře následující obrazovka.

Byl otevřen nástroj JavaDoc

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:

Výstupní okno JavaDoc

  • Po dokončení generování se vygenerují následující soubory.

Generování JavaDoc

  • 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.

Organizované dokumenty API

  • Podobně je uveden níže ukázkový obsah v souboru Main.html

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í

^