what is javadoc how use it generate documentation
W tym samouczku wyjaśniono, czym są narzędzie JavaDoc i JavaDoc. Komentarze i metody generowania dokumentacji kodu:
JavaDoc to specjalne narzędzie dostarczane z JDK. Służy do generowania dokumentacji kodu źródłowego Java w formacie HTML.
Jest to generator dokumentacji dla języka Java firmy Sun Microsystems (obecnie Oracle Corporation).
=> Sprawdź WSZYSTKIE samouczki Java tutaj.
Czego się nauczysz:
Co to jest JavaDoc
To narzędzie korzysta z formatu „komentarzy doc” do dokumentowania klas Java. IDE, takie jak Eclipse, IntelliJIDEA lub NetBeans, mają wbudowane narzędzie JavaDoc do generowania dokumentacji HTML. Na rynku mamy również wiele edytorów plików, które mogą pomóc programiście w tworzeniu źródeł JavaDoc.
Oprócz dokumentacji kodu źródłowego narzędzie to udostępnia również API, które tworzy „doclety” i „tagi”, których używamy do analizy struktury aplikacji Java.
Należy zauważyć, że to narzędzie w żaden sposób nie wpływa na wydajność aplikacji, ponieważ kompilator usuwa wszystkie komentarze podczas kompilacji programu Java.
Pisanie komentarzy w programie, a następnie używanie JavaDoc do generowania dokumentacji ma pomóc programiście / użytkownikowi w zrozumieniu kodu.
Dokumentacja HTML generowana przez JavaDoc to dokumentacja API. Analizuje deklaracje i generuje zestaw plików źródłowych. Plik źródłowy zawiera opis pól, metod, konstruktorów i klas.
Zwróć uwagę, że zanim użyjemy narzędzia JavaDoc w naszym kodzie źródłowym, musimy uwzględnić w programie specjalne komentarze JavaDoc.
Przejdźmy teraz do komentarzy.
Komentarze JavaDoc
Język Java obsługuje następujące typy komentarzy.
# 1) Komentarze jednowierszowe: Komentarz jednowierszowy jest oznaczony jako „ // ”I kiedy kompilator je napotyka, ignoruje wszystko, co następuje po tych komentarzach do końca wiersza.
# 2) Wielowierszowe komentarze: Komentarze wielowierszowe są przedstawiane za pomocą „ /*….*/ ”. Tak więc po napotkaniu sekwencji „/ *” kompilator ignoruje wszystko, co następuje po tej sekwencji, aż napotka sekwencję zamykającą „* /”.
# 3) Uwagi do dokumentacji: Nazywane są one komentarzami Doc i są używane przez narzędzie do generowania dokumentacji API. Komentarze do dokumentu są oznaczone jako „ / ** dokumentacja * / ”. Jak widać, te komentarze różnią się od zwykłych komentarzy opisanych powyżej. Komentarze do dokumentów mogą również zawierać w sobie tagi HTML, co wkrótce zobaczymy.
jak uruchomić plik swf w chrome
Aby wygenerować dokumentację API za pomocą tego narzędzia, musimy dostarczyć te komentarze do dokumentacji (komentarze do dokumentacji) w naszym programie.
Struktura komentarza JavaDoc
Struktura komentarza Doc w Javie jest podobna do komentarza wielowierszowego, z tym wyjątkiem, że komentarz doc ma dodatkową gwiazdkę (*) w otwierającym tagu. Dlatego komentarz do dokumentu zaczyna się od „/ **” zamiast „/ *”.
Ponadto komentarze w stylu JavaDoc mogą również zawierać znaczniki HTML.
Format komentarzy JavaDoc
W oparciu o konstrukcję programistyczną, na podstawie której chcemy udokumentować, możemy umieścić komentarze doc nad dowolną konstrukcją, taką jak klasa, metoda, pole itp. Przejdźmy przez przykłady komentarzy do dokumentacji każdej konstrukcji.
Format poziomu klasy
Format komentarza do dokumentu na poziomie klasy będzie wyglądał tak, jak pokazano poniżej:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods }
Jak pokazano powyżej, komentarz do dokumentu na poziomie klasy będzie zawierał wszystkie szczegóły, w tym autora zajęć, ewentualne linki itp.
Format poziomu metody
Poniżej podano przykład formatu doc na poziomie 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 widać z powyższego przykładu, w komentarzu doc metody możemy mieć dowolną liczbę tagów. Możemy również mieć akapity w opisie komentarza wskazanym przez
...
.Mamy również specjalne tagi opisujące zwracaną wartość (@return) i parametry metody (@param).
Format poziomu pola
Poniższy przykład przedstawia komentarz dokumentu dotyczący pola.
/** * The public name of a message */ private String msg_txt;
Jak widać z powyższego przykładu, możemy również mieć zwykłe komentarze bez żadnych tagów. Należy zauważyć, że JavaDoc nie generuje żadnej dokumentacji dla pól prywatnych, chyba że określimy opcję prywatną za pomocą polecenia JavaDoc.
Omówmy teraz tagi używane w komentarzach do dokumentu.
Tagi JavaDoc
Java udostępnia różne znaczniki, które możemy umieścić w komentarzu do dokumentu. Kiedy używamy tych tagów, narzędzie analizuje je w celu wygenerowania dobrze sformatowanego interfejsu API z kodu źródłowego.
W każdym tagu rozróżniana jest wielkość liter i zaczyna się od znaku „@”. Każdy tag zaczyna się na początku wiersza, jak widać na powyższych przykładach. W przeciwnym razie kompilator traktuje to jak zwykły tekst. Zgodnie z konwencją te same znaczniki są umieszczane razem.
Istnieją dwa typy tagów, których możemy używać w komentarzach do dokumentu.
1) Blokuj tagi : Tagi bloków mają postać @Nazwa znacznika .
Tagi blokowe można umieścić w sekcji tagów i postępować zgodnie z głównym opisem .
# 2) Tagi wbudowane :Tagi wbudowane są ujęte w nawiasy klamrowe i mają postać, {@Nazwa znacznika} . Znaczniki wbudowane można umieścić w dowolnym miejscu w komentarzu do dokumentu.
W poniższej tabeli wymieniono wszystkie znaczniki, których można używać w komentarzach do dokumentu.
Etykietka | Opis | Dotyczy |
---|---|---|
@return opis | Zawiera opis wartości zwracanej. | metoda |
@author xyz | Wskazuje autora klasy, interfejsu lub wyliczenia. | Klasa, interfejs, wyliczenie |
{@docRoot} | Ten znacznik zawiera ścieżkę względną do katalogu głównego dokumentu. | Klasa, interfejs, wyliczenie, pole, metoda |
Wersja @wersja | Określa wpis wersji oprogramowania. | Klasa, interfejs, wyliczenie |
@since since-text | Określa, od kiedy istnieje ta funkcja | Klasa, interfejs, wyliczenie, pole, metoda |
@ zobacz odniesienie | Określa odniesienia (łącza) do innej dokumentacji | Klasa, interfejs, wyliczenie, pole, metoda |
Opis nazwy @param | Używane do opisu parametru / argumentu metody. | metoda |
Opis nazwy klasy @ wyjątku | Określa wyjątek, który metoda może zgłosić w swoim kodzie. | metoda |
Opis nazwy klasy @throws | ||
@deprecated description | Określa, czy metoda jest nieaktualna | Klasa, interfejs, wyliczenie, pole, metoda |
{@inheritDoc} | Służy do kopiowania opisu z nadpisanej metody w przypadku dziedziczenia | Metoda zastępująca |
{@link reference} | Zawiera odniesienia lub łącza do innych symboli. | Klasa, interfejs, wyliczenie, pole, metoda |
{@linkplain reference} | To samo co {@link}, ale jest wyświetlane jako zwykły tekst. | Klasa, interfejs, wyliczenie, pole, metoda |
{@value #STATIC_FIELD} | Opisz wartość pola statycznego. | Pole statyczne |
{@code literal} | Służy do formatowania tekstu literału czcionką kodu podobną do {@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.
Uruchom pliki .jar w systemie Windows 10
#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!!'); } }
Wiemy, że nie musimy kompilować programu ani projektu, aby wygenerować JavaDoc. IntelliJIdea Ide zapewnia wbudowane narzędzie do generowania dokumentacji. Wykonaj poniższe kroki, aby wygenerować dokumentację za pomocą IntelliJIdea.
- Kliknij Narzędzia -> Generuj JavaDoc
- Poniższy ekran jest otwierany po kliknięciu narzędzia JavaDoc.
Tutaj możemy określić, czy chcemy wygenerować dokumentację dla całego projektu, czy tylko jednej klasy itp. Możemy również określić katalog wyjściowy, w którym będą generowane pliki dokumentacji. Istnieją różne inne specyfikacje, jak pokazano na powyższym rysunku.
Kliknij OK po określeniu wszystkich parametrów.
- Teraz możemy zobaczyć proces generowania Java Doc w oknie wyjściowym. Przykładowe okno wyjściowe dokumentu Java wygląda jak poniżej:
- Po zakończeniu generowania generowane są następujące pliki.
- Zgodnie z określeniem klasy Main generowany jest plik Main.html. Zwróć uwagę, że plik index.html również ma taką samą zawartość, jak plik Main.html.
- Plik help-doc.html zawiera ogólne definicje encji Java. Poniżej pokazano przykładową zawartość tego pliku.
- Podobnie poniżej podana jest przykładowa treść w pliku Main.html
W ten sposób możemy wygenerować dokumentację za pomocą tego narzędzia w idei IntelliJ. Podobne kroki możemy wykonać w innych środowiskach Java IDE, takich jak Eclipse i / lub NetBeans.
Często Zadawane Pytania
Pytanie 1) Jakie jest zastosowanie JavaDoc?
Odpowiedź: Narzędzie JavaDoc jest dostarczane z JDK. Służy do generowania dokumentacji kodu źródłowego Java w formacie HTML. To narzędzie wymaga, aby komentarze w kodzie źródłowym były dostarczane w predefiniowanym formacie /**….*/. Nazywa się to również komentarzami do dokumentów.
P # 2) Jaki jest przykład dokumentacji Java?
Odpowiedź: Narzędzie dokumentacji Java Doc generuje pliki HTML, dzięki czemu możemy przeglądać dokumentację z poziomu przeglądarki internetowej. Prawdziwym przykładem dokumentacji JavaDoc jest dokumentacja bibliotek Java w Oracle Corporation, http://download.oracle.com/javase/6/ dokumenty /ogień/.
Pytanie 3) Czy metody prywatne wymagają JavaDoc?
Odpowiedź: Nie. Pola prywatne i metody są przeznaczone tylko dla programistów. Nie ma logiki w dostarczaniu dokumentacji dotyczącej prywatnych metod lub pól, które nie są dostępne dla użytkownika końcowego. Java Doc nie generuje również dokumentacji dla podmiotów prywatnych.
różnica między serwerem klienta a aplikacją internetową
P # 4) Co to jest komenda JavaDoc?
Odpowiedź: To polecenie analizuje deklaracje i komentarze dokumentów w plikach źródłowych Java i generuje odpowiednie strony dokumentacji HTML zawierające dokumentację dla klas publicznych i chronionych, klas zagnieżdżonych, konstruktorów, metod, pól i interfejsów.
Jednak JavaDoc nie generuje dokumentacji dla jednostek prywatnych i anonimowych klas wewnętrznych.
Wniosek
W tym samouczku opisano narzędzie JavaDoc w pakiecie JDK, które jest przydatne do generowania dokumentacji kodu źródłowego Java w formacie HTML. Dokumentację możemy wygenerować, wykonując polecenie Java Doc za pomocą narzędzia poleceń lub korzystając z wbudowanej funkcjonalności JavaDoc dostępnej w większości środowisk Java IDE.
Widzieliśmy, jak możemy użyć narzędzia z IntelliJIdea Java IDE do generowania dokumentacji. W samouczku wyjaśniono również różne znaczniki, których można używać z komentarzami do dokumentów, dzięki czemu narzędzie może generować przyjazną dla użytkownika dokumentację zawierającą szczegółowe informacje dotyczące kodu źródłowego.
=> Odwiedź tutaj, aby nauczyć się języka Java od podstaw.
rekomendowane lektury
- Podstawy języka Java: składnia języka Java, klasa języka Java i podstawowe pojęcia dotyczące języka Java
- Wdrażanie Java: tworzenie i wykonywanie pliku Java JAR
- Wirtualna maszyna Java: jak JVM pomaga w uruchamianiu aplikacji Java
- Samouczek JAVA dla początkujących: ponad 100 praktycznych samouczków wideo Java
- Klasa Java Integer i Java BigInteger z przykładami
- Komponenty Java: platforma Java, JDK, JRE i wirtualna maszyna Java
- Jak stworzyć dokumentację API w Postman?