what is javadoc how use it generate documentation
Acest tutorial explică ce sunt instrumentul JavaDoc și comentariile JavaDoc și metodele de generare a documentației de cod:
JavaDoc este un instrument special care este împachetat cu JDK. Este folosit pentru a genera documentația codului codului sursă Java în format HTML.
Este un generator de documentație pentru limbajul Java de la Sun Microsystems (în prezent Oracle Corporation).
=> Verificați TOATE Tutorialele Java aici.
Ce veți învăța:
Ce este JavaDoc
Acest instrument folosește formatul „comentarii doc” pentru a documenta clasele Java. IDE-uri precum Eclipse, IntelliJIDEA sau NetBeans au un instrument JavaDoc încorporat pentru a genera documentație HTML. Avem, de asemenea, mulți editori de fișiere pe piață care pot ajuta programatorul să producă surse JavaDoc.
În afară de documentația codului sursă, acest instrument oferă și API care creează „docleturi” și „tagleturi” pe care le folosim pentru a analiza structura unei aplicații Java.
Un punct de remarcat este că acest instrument nu afectează în niciun fel performanța aplicației, deoarece compilatorul elimină toate comentariile din timpul compilării programului Java.
Scrierea comentariilor în program și apoi utilizarea JavaDoc pentru a genera documentația este de a ajuta programatorul / utilizatorul să înțeleagă codul.
Documentația HTML generată de JavaDoc este documentația API. Analizează declarațiile și generează un set de fișiere sursă. Fișierul sursă descrie câmpuri, metode, constructori și clase.
Rețineți că, înainte de a utiliza instrumentul JavaDoc pe codul nostru sursă, trebuie să includem comentarii speciale JavaDoc în program.
Să trecem acum la comentarii.
Comentarii JavaDoc
Limbajul Java acceptă următoarele tipuri de comentarii.
# 1) Comentarii cu o singură linie: Comentariul cu o singură linie este notat cu „ // ”Și când compilatorul întâlnește acestea, ignoră tot ce urmează acestor comentarii până la sfârșitul liniei.
# 2) Comentarii pe mai multe linii: Comentariile pe mai multe linii sunt reprezentate folosind „ /*….*/ ”. Deci, la întâlnirea secvenței ‘/ *’, compilatorul ignoră tot ce urmează această secvență până când întâlnește secvența de închidere ‘* /’.
# 3) Comentarii despre documentație: Acestea se numesc comentarii Doc și sunt utilizate de instrument pentru a genera documentația API. Comentariile doc sunt indicate ca „ /** documentație */ ”. După cum putem vedea, aceste comentarii sunt diferite de comentariile normale descrise mai sus. Comentariile doc pot conține, de asemenea, etichete HTML în interior, așa cum vom vedea în scurt timp.
cum se obține cheia de securitate pentru wifi
Deci, pentru a genera documentația API folosind acest instrument, trebuie să furnizăm aceste comentarii despre documentație (comentarii doc) în programul nostru.
Structura unui comentariu JavaDoc
Structura comentariului Doc în Java este similară cu comentariul pe mai multe linii, cu excepția faptului că comentariul doc are un asterisc suplimentar (*) în eticheta de deschidere. Deci, comentariul doc începe cu „/ **” în loc de „/ *”.
În plus, comentariile în stil JavaDoc pot avea și etichete HTML în interior.
Format de comentarii JavaDoc
Pe baza construcției de programare pe care dorim să o documentăm, putem plasa comentariile doc deasupra oricărui construct, cum ar fi clasa, metoda, câmpul, etc. Să trecem prin exemple ale fiecăruia dintre comentariile doc ale constructelor.
Format la nivel de clasă
Formatul de comentariu doc la nivel de clasă va arăta așa cum se arată mai jos:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } După cum se arată mai sus, un comentariu doc la nivel de clasă va conține toate detaliile, inclusiv autorul clasei, link-uri, dacă există, etc.
Format nivel metodă
Dat mai jos este un exemplu de format doc la nivel de metodă.
/** * 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; } După cum putem vedea din exemplul de mai sus, putem avea orice număr de etichete în comentariul doc al metodei. De asemenea, putem avea paragrafe în descrierea comentariilor indicate de
...
.De asemenea, avem etichete speciale pentru a descrie valoarea returnată (@return) și parametrii metodei (@param).
Format la nivel de câmp
Următorul exemplu arată comentariul pentru un câmp.
/** * The public name of a message */ private String msg_txt;După cum se vede din exemplul de mai sus, putem avea și comentarii simple, fără etichete. Rețineți că JavaDoc nu generează nicio documentație pentru câmpurile private decât dacă specificăm o opțiune privată cu comanda JavaDoc.
Acum, să discutăm etichetele utilizate cu comentariile doc.
Etichete JavaDoc
Java oferă diverse etichete pe care le putem include în comentariul doc. Când folosim aceste etichete, instrumentul analizează aceste etichete pentru a genera un API bine formatat din codul sursă.
Fiecare etichetă este sensibilă la majuscule și minuscule și începe cu un semn „@”. Fiecare etichetă începe la începutul liniei, după cum putem vedea din exemplele de mai sus. În caz contrar, compilatorul îl tratează ca pe un text normal. Ca o convenție, aceleași etichete sunt plasate împreună.
Există două tipuri de etichete pe care le putem folosi în comentariul doc.
# 1) Blocați etichetele : Etichetele de blocuri au forma @nume eticheta .
Etichetele de bloc pot fi plasate în secțiunea de etichete și urmează descrierea principală .
poți folosi orice cască vr pentru ps4
# 2) Etichete în linie :Etichetele în linie sunt încadrate în acolade și sunt de formă, {@nume eticheta} . Etichetele inline pot fi plasate oriunde în interiorul comentariului doc.
Următorul tabel listează toate etichetele care pot fi utilizate în comentariile doc.
| Etichetă | Descriere | Se aplică la |
|---|---|---|
| @descriere retur | Oferă descrierea valorii returnate. | Metodă |
| @autor xyz | Indică autorul clasei, interfeței sau enum. | Clasă, interfață, Enum |
| {@docRoot} | Această etichetă are calea relativă către directorul rădăcină al documentului. | Clasă, interfață, Enum, câmp, metodă |
| @versiune versiune | Specifică introducerea versiunii software. | Clasă, interfață, Enum |
| @de când textul | Specifică de când există această funcționalitate | Clasă, interfață, Enum, câmp, metodă |
| @vezi referință | Specifică referințe (legături) la alte documente | Clasă, interfață, Enum, câmp, metodă |
| @param descrierea numelui | Folosit pentru a descrie parametrul / argumentul metodei. | Metodă |
| @exception descriere nume clasă | Specifică excepția pe care metoda o poate arunca în codul său. | Metodă |
| @throws descrierea numelui clasei | ||
| @descriere depreciată | Specifică dacă metoda este depășită | Clasă, interfață, Enum, câmp, metodă |
| {@inheritDoc} | Folosit pentru a copia descrierea din metoda suprascrisă în caz de moștenire | Metoda de suprascriere |
| {@link reference} | Oferă referințe sau linkuri către alte simboluri. | Clasă, interfață, Enum, câmp, metodă |
| {@linkplain reference} | La fel ca {@link}, dar este afișat în text simplu. | Clasă, interfață, Enum, câmp, metodă |
| {@value #STATIC_FIELD} | Descrieți valoarea unui câmp static. | Câmp static |
| {@code literal} | Folosit pentru a formata textul literal în font de cod similar cu {@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!!'); } } Știm că nu trebuie să compilăm programul sau proiectul pentru a genera JavaDoc. IntelliJIdea Ide oferă un instrument încorporat pentru a genera documentația. Urmați pașii de mai jos pentru a genera documentația utilizând IntelliJIdea.
- Faceți clic pe Instrumente -> Generați JavaDoc
- Următorul ecran se deschide când se face clic pe instrumentul JavaDoc.
Aici putem specifica dacă dorim să generăm documentație pentru întregul proiect sau doar o singură clasă etc. Putem specifica și directorul de ieșire în care vor fi generate fișierele de documentare. Există diverse alte specificații, așa cum se arată în figura de mai sus.
Faceți clic pe OK după ce toți parametrii sunt specificați.
- Acum putem vedea procesul de generare Java Doc în fereastra de ieșire. Un exemplu de fereastră de ieșire Java Doc arată așa cum se arată mai jos:
- După finalizarea generației, sunt generate următoarele fișiere.
- După cum am specificat clasa Main, este generat fișierul Main.html. Rețineți că index.html are, de asemenea, același conținut ca Main.html.
- Fișierul help-doc.html conține definiții generale ale entităților Java. Un eșantion de conținut al acestui fișier este prezentat mai jos.
- În mod similar, prezentat mai jos este un eșantion de conținut în fișierul Main.html
Astfel, acesta este modul în care putem genera documentație folosind acest instrument în ideea IntelliJ. Putem urma pași similari în alte IDE Java, cum ar fi Eclipse și / sau NetBeans.
întrebări frecvente
Q # 1) La ce folosește JavaDoc?
Răspuns: Instrumentul JavaDoc vine cu JDK. Este folosit pentru a genera documentația de cod pentru codul sursă Java în format HTML. Acest instrument necesită ca comentariile din codul sursă să fie furnizate într-un format predefinit ca /**….*/. Acestea se mai numesc și comentarii doc.
Q # 2) Care este exemplul de documentare Java?
Răspuns: Instrumentul de documentare Java Doc generează fișiere HTML, astfel încât să putem vizualiza documentația din browserul web. Exemplul real de documentare JavaDoc este documentația pentru bibliotecile Java de la Oracle Corporation, http://download.oracle.com/javase/6/ documente /foc/.
Î # 3) Metodele private au nevoie de JavaDoc?
Răspuns: Nu. Câmpurile și metodele private sunt doar pentru dezvoltatori. Nu există nicio logică în furnizarea documentației pentru metode sau câmpuri private care nu sunt accesibile utilizatorului final. Java Doc, de asemenea, nu generează documentație pentru entitățile private.
care este cel mai bun program pentru a vă curăța computerul
Q # 4) Ce este Comanda JavaDoc?
Răspuns: Această comandă analizează declarațiile și comentariile doc din fișierele sursă Java și generează pagini de documentație HTML corespunzătoare care conțin documentație pentru clase publice și protejate, clase imbricate, constructori, metode, câmpuri și interfețe.
Cu toate acestea, JavaDoc nu generează documentație pentru entități private și clase interioare anonime.
Concluzie
Acest tutorial a descris instrumentul JavaDoc ambalat cu JDK, care este util pentru generarea documentației de cod pentru codul sursă Java în format HTML. Putem genera documentație fie prin executarea comenzii Java Doc prin instrumentul de comandă, fie prin utilizarea funcționalității JavaDoc încorporate disponibile în majoritatea IDE-urilor Java.
Am văzut cum putem folosi instrumentul cu IntelliJIdea Java IDE pentru a genera documentație. Tutorialul a explicat, de asemenea, diferite etichete care pot fi utilizate cu comentariile doc, astfel încât instrumentul să poată genera documentație ușor de utilizat care detaliază toate informațiile legate de codul sursă.
=> Vizitați aici pentru a afla Java de la zero.
Lectură recomandată
- Noțiuni de bază Java: Sintaxă Java, Java Class și concepte de bază Java
- Implementarea Java: crearea și executarea fișierului Java JAR
- Mașină virtuală Java: Cum ajută JVM la rularea aplicației Java
- Tutorial JAVA pentru începători: peste 100 de cursuri video Java practice
- Java Integer și Java BigInteger Class cu exemple
- Componente Java: platformă Java, JDK, JRE și mașină virtuală Java
- Cum se creează documentația API în Postman?