what is javadoc how use it generate documentation
Aquest tutorial explica què són l'eina JavaDoc i els comentaris i mètodes JavaDoc per generar documentació de codi:
JavaDoc és una eina especial empaquetada amb el JDK. S'utilitza per generar la documentació del codi del codi font de Java en format HTML.
És un generador de documentació per al llenguatge Java de Sun Microsystems (actualment Oracle Corporation).
=> Consulteu TOTS els tutorials de Java aquí.
Què aprendreu:
Què és JavaDoc
Aquesta eina utilitza el format de 'comentaris doc' per documentar classes de Java. Els IDE com Eclipse, IntelliJIDEA o NetBeans tenen una eina JavaDoc integrada per generar documentació HTML. També tenim molts editors de fitxers al mercat que poden ajudar el programador a produir fonts JavaDoc.
A part de la documentació del codi font, aquesta eina també proporciona una API que crea 'doclets' i 'taglets' que fem servir per analitzar l'estructura d'una aplicació Java.
Un punt a destacar és que aquesta eina no afecta el rendiment de l’aplicació de cap manera, ja que el compilador elimina tots els comentaris durant la compilació del programa Java.
Escriure comentaris al programa i després utilitzar JavaDoc per generar la documentació és ajudar el programador / usuari a entendre el codi.
La documentació HTML generada per JavaDoc és documentació de l'API. Analitza les declaracions i genera un conjunt de fitxers font. El fitxer font descriu camps, mètodes, constructors i classes.
Tingueu en compte que abans d’utilitzar l’eina JavaDoc al nostre codi font, hem d’incloure comentaris especials de JavaDoc al programa.
Passem ara als comentaris.
Comentaris de JavaDoc
El llenguatge Java admet els següents tipus de comentaris.
# 1) Comentaris d'una sola línia: El comentari d'una sola línia es denota per ' // ”I quan el compilador els troba, ignora tot el que segueix aquests comentaris fins al final de la línia.
# 2) Comentaris de línies múltiples: Els comentaris multilínia es representen mitjançant ' /*....*/ ”. Així, en trobar-se amb la seqüència ‘/ *’, el compilador ignora tot el que segueix aquesta seqüència fins que troba la seqüència de tancament ‘* /’.
# 3) Comentaris de la documentació: S’anomenen comentaris Doc i són utilitzats per l’eina per generar documentació de l’API. Els comentaris del document s’indiquen com a “ / ** documentació * / ”. Com podem veure, aquests comentaris són diferents dels comentaris normals descrits anteriorment. Els comentaris del document també poden contenir etiquetes HTML al seu interior, tal com veurem en breu.
preguntes i respostes d’entrevistes de proves d’aplicacions web
Per tant, per generar documentació de l'API mitjançant aquesta eina, hem de proporcionar aquests comentaris de documentació (comentaris de documents) al nostre programa.
Estructura d'un comentari JavaDoc
L'estructura del comentari del document a Java és similar al comentari de diverses línies, tret que el comentari del document té un asterisc addicional (*) a l'etiqueta d'obertura. Per tant, el comentari del document comença per ‘/ **’ en lloc de ‘/ *’.
A més, els comentaris a l'estil JavaDoc també poden contenir etiquetes HTML.
Format de comentaris JavaDoc
Basant-nos en la construcció de programació sobre la qual volem documentar, podem situar els comentaris de documents per sobre de qualsevol construcció com ara la classe, el mètode, el camp, etc. Anem a veure exemples de cadascun dels comentaris de documents de les construccions.
Format de nivell de classe
El format de comentari del document a nivell de classe serà el següent:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } Com es mostra més amunt, un comentari de document a nivell de classe contindrà tots els detalls, inclòs l’autor de la classe, si hi ha enllaços, etc.
Format de nivell de mètode
A continuació es mostra un exemple de format doc a nivell de mètode.
/** * 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; } Com podem veure a l'exemple anterior, podem tenir qualsevol nombre d'etiquetes al comentari doc del mètode. També podem incloure paràgrafs a la descripció del comentari indicada per
...
.També tenim etiquetes especials per descriure el valor de retorn (@return) i els paràmetres del mètode (@param).
Format de nivell de camp
L'exemple següent mostra el comentari del document per a un camp.
caràcter a cadena c ++
/** * The public name of a message */ private String msg_txt;Com es veu a l'exemple anterior, també podem fer comentaris simples sense etiquetes. Tingueu en compte que JavaDoc no genera cap documentació per a camps privats tret que especifiquem una opció privada amb l'ordre JavaDoc.
Ara parlem de les etiquetes que s’utilitzen amb els comentaris del document.
Etiquetes JavaDoc
Java proporciona diverses etiquetes que podem incloure al comentari del document. Quan fem servir aquestes etiquetes, l'eina analitza aquestes etiquetes per generar una API ben formatada a partir del codi font.
Cada etiqueta distingeix entre majúscules i minúscules i comença amb un signe '@'. Cada etiqueta comença al principi de la línia, tal com podem veure en els exemples anteriors. En cas contrari, el compilador el tracta com un text normal. Com a convenció, les mateixes etiquetes es col·loquen juntes.
Hi ha dos tipus d’etiquetes que podem utilitzar al comentari del document.
# 1) Etiquetes de blocs : Les etiquetes de bloc tenen la forma de @ nom_etiqueta .
Les etiquetes de bloc es poden col·locar a la secció d’etiquetes i seguir la descripció principal .
# 2) Etiquetes en línia :Les etiquetes en línia estan incloses entre claus i són de la forma, {@tag_name} . Les etiquetes en línia es poden col·locar a qualsevol lloc del comentari del document.
A la taula següent es mostren totes les etiquetes que es poden utilitzar als comentaris del document.
| Etiqueta | Descripció | S'aplica a |
|---|---|---|
| descripció de @torn | Ofereix una descripció del valor de retorn. | Mètode |
| @author xyz | Indica l'autor de la classe, interfície o enum. | Classe, interfície, Enum |
| {@docRoot} | Aquesta etiqueta té el camí relatiu al directori arrel del document. | Classe, Interfície, Enum, Camp, Mètode |
| versió @version | Especifica l'entrada de la versió del programari. | Classe, interfície, Enum |
| @since des del text | Especifica des de quan existeix aquesta funcionalitat | Classe, Interfície, Enum, Camp, Mètode |
| @ veure referència | Especifica referències (enllaços) a altra documentació | Classe, Interfície, Enum, Camp, Mètode |
| descripció del nom @param | S'utilitza per descriure el paràmetre / argument del mètode. | Mètode |
| @exception descripció del nom de classe | Especifica l'excepció que el mètode pot introduir al seu codi. | Mètode |
| Descripció del nom de classe @throws | ||
| @ descripció obsoleta | Especifica si el mètode està obsolet | Classe, Interfície, Enum, Camp, Mètode |
| {@inheritDoc} | S'utilitza per copiar la descripció del mètode anul·lat en cas d'herència | Mètode de substitució |
| {@link reference} | Proporciona referències o enllaços a altres símbols. | Classe, Interfície, Enum, Camp, Mètode |
| {@linkplain reference} | Igual que {@link}, però es mostra en text pla. | Classe, Interfície, Enum, Camp, Mètode |
| {@value #STATIC_FIELD} | Descriviu el valor d'un camp estàtic. | Camp estàtic |
| {@code literal} | S'utilitza per formatar el text literal amb un tipus de lletra de codi similar a {@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!!'); } } Sabem que no necessitem compilar el programa o projecte per generar JavaDoc. IntelliJIdea Ide proporciona una eina integrada per generar la documentació. Seguiu els passos següents per generar la documentació mitjançant IntelliJIdea.
- Feu clic a Eines -> Genera JavaDoc
- La següent pantalla s'obre quan es fa clic a l'eina JavaDoc.
Aquí podem especificar si volem generar documentació per a tot el projecte o només una classe, etc. També podem especificar el directori de sortida on es generaran els fitxers de documentació. Hi ha diverses altres especificacions que es mostren a la figura anterior.
Feu clic a D'acord un cop especificats tots els paràmetres.
- Ara podem veure el procés de generació de Java Doc a la finestra de sortida. Una finestra de sortida de Java Doc d’exemple té el següent aspecte:
- Un cop finalitzada la generació, es generen els fitxers següents.
- Tal com hem especificat la classe Main, es genera el fitxer Main.html. Tingueu en compte que index.html també té el mateix contingut que Main.html.
- El fitxer help-doc.html conté definicions generals d’entitats Java. A continuació es mostra una mostra del contingut d’aquest fitxer.
- De la mateixa manera, a continuació es mostra un contingut de mostra al fitxer Main.html
Per tant, aquesta és la manera en què podem generar documentació mitjançant aquesta eina en la idea IntelliJ. Podem seguir passos similars en altres IDE de Java com Eclipse i / o NetBeans.
Preguntes freqüents
P # 1) Què utilitza JavaDoc?
Resposta: L’eina JavaDoc ve amb JDK. S'utilitza per generar la documentació del codi per al codi font de Java en format HTML. Aquesta eina requereix que els comentaris del codi font es proporcionin en un format predefinit com /**….*/. També s’anomenen comentaris doc.
Q # 2) Quin és l'exemple de documentació de Java?
Resposta: L'eina de documentació Java Doc genera fitxers HTML perquè puguem veure la documentació des del navegador web. L’exemple real de la documentació JavaDoc és la documentació per a les biblioteques Java d’Oracle Corporation, http://download.oracle.com/javase/6/ documents / foc /.
P # 3) Els mètodes privats necessiten JavaDoc?
Resposta: No. Els camps i mètodes privats són només per a desenvolupadors. No hi ha cap lògica en proporcionar documentació per a mètodes o camps privats que no siguin accessibles per a l'usuari final. Java Doc tampoc no genera documentació per a entitats privades.
preguntes i respostes d'entrevistes per a Android pdf
Q # 4) Què és l'ordre JavaDoc?
Resposta: Aquesta ordre analitza les declaracions i els comentaris de documents als fitxers font de Java i genera les pàgines de documentació HTML corresponents que contenen documentació per a classes públiques i protegides, classes imbricades, constructors, mètodes, camps i interfícies.
Tot i això, JavaDoc no genera documentació per a entitats privades i classes internes anònimes.
Conclusió
Aquest tutorial descriu l'eina JavaDoc empaquetada amb JDK que és útil per generar la documentació del codi per al codi font Java en format HTML. Podem generar documentació mitjançant l'execució de l'ordre Java Doc mitjançant l'eina d'ordres o mitjançant la funcionalitat JavaDoc integrada disponible a la majoria dels IDE de Java.
Vam veure com podem utilitzar l'eina amb IntelliJIdea Java IDE per generar documentació. El tutorial també explicava diverses etiquetes que es poden utilitzar amb els comentaris del document perquè l'eina pugui generar documentació fàcil d'utilitzar que detalli tota la informació relacionada amb el codi font.
=> Visiteu aquí per aprendre Java des de zero.
Lectura recomanada
- Conceptes bàsics de Java: sintaxi de Java, Java Class i conceptes bàsics de Java
- Desplegament de Java: creació i execució del fitxer JAR de Java
- Màquina virtual Java: com ajuda JVM a executar aplicacions Java
- Tutorial JAVA per a principiants: més de 100 tutorials pràctics de vídeo Java
- Java Integer i Java BigInteger Class amb exemples
- Components de Java: plataforma Java, JDK, JRE i màquina virtual de Java
- Com es crea documentació API a Postman?