what is javadoc how use it generate documentation
Ce didacticiel explique ce que sont l'outil JavaDoc et les commentaires et méthodes JavaDoc pour générer la documentation du code:
JavaDoc est un outil spécial fourni avec le JDK. Il est utilisé pour générer la documentation du code source Java au format HTML.
Il s'agit d'un générateur de documentation pour le langage Java de Sun Microsystems (actuellement Oracle Corporation).
=> Consultez TOUS les didacticiels Java ici.
Ce que vous apprendrez:
Qu'est-ce que JavaDoc
Cet outil utilise le format «doc comments» pour documenter les classes Java. Les IDE comme Eclipse, IntelliJIDEA ou NetBeans ont un outil JavaDoc intégré pour générer de la documentation HTML. Nous avons également de nombreux éditeurs de fichiers sur le marché qui peuvent aider le programmeur à produire des sources JavaDoc.
Outre la documentation du code source, cet outil fournit également une API qui crée des «doclets» et des «taglets» que nous utilisons pour analyser la structure d'une application Java.
Un point à noter est que cet outil n'affecte en aucun cas les performances de l'application car le compilateur supprime tous les commentaires lors de la compilation du programme Java.
Ecrire des commentaires dans le programme puis utiliser JavaDoc pour générer la documentation est d'aider le programmeur / utilisateur à comprendre le code.
La documentation HTML générée par JavaDoc est la documentation API. Il analyse les déclarations et génère un ensemble de fichiers source. Le fichier source décrit les champs, les méthodes, les constructeurs et les classes.
Notez qu'avant d'utiliser l'outil JavaDoc sur notre code source, nous devons inclure des commentaires JavaDoc spéciaux dans le programme.
Passons maintenant aux commentaires.
Commentaires JavaDoc
Le langage Java prend en charge les types de commentaires suivants.
# 1) Commentaires sur une seule ligne: Le commentaire sur une seule ligne est indiqué par ' // »Et lorsque le compilateur les rencontre, il ignore tout ce qui suit ces commentaires jusqu'à la fin de la ligne.
# 2) Commentaires multilignes: Les commentaires multilignes sont représentés par ' /*….*/ ». Ainsi, en rencontrant la séquence ‘/ *’, le compilateur ignore tout ce qui suit cette séquence jusqu’à ce qu’il rencontre la séquence de fermeture ‘* /’.
# 3) Commentaires sur la documentation: Ceux-ci sont appelés commentaires Doc et sont utilisés par l'outil pour générer la documentation API. Les commentaires du document sont indiqués comme ' /** Documentation */ ». Comme nous pouvons le voir, ces commentaires sont différents des commentaires normaux décrits ci-dessus. Les commentaires de la documentation peuvent également contenir des balises HTML à l'intérieur comme nous le verrons sous peu.
pointeurs de liste chaînée c ++
Donc pour générer la documentation API à l'aide de cet outil, nous devons fournir ces commentaires de documentation (commentaires doc) dans notre programme.
Structure d'un commentaire JavaDoc
La structure du commentaire Doc en Java est similaire au commentaire multiligne sauf que le commentaire doc a un astérisque supplémentaire (*) dans la balise d'ouverture. Le commentaire du document commence donc par «/ **» au lieu de «/ *».
De plus, les commentaires de style JavaDoc peuvent également contenir des balises HTML.
Format de commentaire JavaDoc
Sur la base de la construction de programmation sur laquelle nous voulons documenter, nous pouvons placer des commentaires doc au-dessus de n'importe quelle construction telle que classe, méthode, champ, etc. Passons en revue des exemples de chacun des commentaires doc des constructions.
Format de niveau de classe
Le format de commentaire doc au niveau de la classe ressemblera à celui ci-dessous:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } Comme indiqué ci-dessus, un commentaire de document au niveau de la classe aura tous les détails, y compris l'auteur de la classe, les liens le cas échéant, etc.
Format de niveau de méthode
Vous trouverez ci-dessous un exemple de format doc au niveau de la méthode.
/** * 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; } Comme nous pouvons le voir dans l'exemple ci-dessus, nous pouvons avoir n'importe quel nombre de balises dans le commentaire doc de la méthode. Nous pouvons également avoir des paragraphes dans la description du commentaire indiqué par
...
.Nous avons également des balises spéciales pour décrire la valeur de retour (@return) et les paramètres de la méthode (@param).
Format au niveau du champ
L'exemple suivant montre le commentaire doc pour un champ.
/** * The public name of a message */ private String msg_txt;Comme le montre l'exemple ci-dessus, nous pouvons également avoir des commentaires simples sans aucune balise. Notez que JavaDoc ne génère aucune documentation pour les champs privés sauf si nous spécifions une option privée avec la commande JavaDoc.
Voyons maintenant les balises utilisées avec les commentaires du document.
Balises JavaDoc
Java fournit diverses balises que nous pouvons inclure dans le commentaire doc. Lorsque nous utilisons ces balises, l'outil analyse ces balises pour générer une API bien formatée à partir du code source.
Chaque balise est sensible à la casse et commence par un signe «@». Chaque balise commence au début de la ligne comme nous pouvons le voir dans les exemples ci-dessus. Sinon, le compilateur le traite comme un texte normal. Par convention, les mêmes balises sont placées ensemble.
Il existe deux types de balises que nous pouvons utiliser dans le commentaire doc.
# 1) Bloquer les balises : Les balises de bloc ont la forme de @tag_name .
Les balises de bloc peuvent être placées dans la section des balises et suivre la description principale .
# 2) Balises en ligne :Les balises en ligne sont placées entre accolades et sont de la forme, {@tag_name} . Les balises en ligne peuvent être placées n'importe où dans le commentaire du document.
Le tableau suivant répertorie toutes les balises pouvant être utilisées dans les commentaires du document.
| Étiqueter | Description | S'applique à |
|---|---|---|
| @return description | Fournit une description de la valeur de retour. | Méthode |
| @auteur xyz | Indique l'auteur de la classe, de l'interface ou de l'énumération. | Classe, interface, énumération |
| {@docRoot} | Cette balise a le chemin relatif vers le répertoire racine du document. | Classe, interface, énumération, champ, méthode |
| @version version | Spécifie l'entrée de la version du logiciel. | Classe, interface, énumération |
| @ depuis le texte depuis | Spécifie depuis quand cette fonctionnalité existe | Classe, interface, énumération, champ, méthode |
| @voir la référence | Spécifie des références (liens) à d'autres documents | Classe, interface, énumération, champ, méthode |
| @param name description | Utilisé pour décrire le paramètre / argument de la méthode. | Méthode |
| @exception nom_classe description | Spécifie l'exception que la méthode peut lancer dans son code. | Méthode |
| @throws description de nom de classe | ||
| @ description obsolète | Spécifie si la méthode est obsolète | Classe, interface, énumération, champ, méthode |
| {@inheritDoc} | Utilisé pour copier la description de la méthode remplacée en cas d'héritage | Méthode de remplacement |
| {@link reference} | Fournit des références ou des liens vers d'autres symboles. | Classe, interface, énumération, champ, méthode |
| {@linkplain reference} | Identique à {@link} mais s'affiche en texte brut. | Classe, interface, énumération, champ, méthode |
| {@value #STATIC_FIELD} | Décrivez la valeur d'un champ statique. | Champ statique |
| {@code literal} | Utilisé pour mettre en forme le texte littéral dans une police de code similaire à {@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.
comment trouver la clé de sécurité réseau sur un téléphone Android
#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!!'); } } Nous savons que nous n'avons pas besoin de compiler le programme ou le projet pour générer JavaDoc. IntelliJIdea Ide fournit un outil intégré pour générer la documentation. Suivez les étapes ci-dessous pour générer la documentation à l'aide d'IntelliJIdea.
- Cliquez sur Outils -> Générer JavaDoc
- L'écran suivant s'ouvre lorsque vous cliquez sur l'outil JavaDoc.
Ici, nous pouvons spécifier si nous voulons générer la documentation pour l'ensemble du projet ou une seule classe, etc. Nous pouvons également spécifier le répertoire de sortie où les fichiers de documentation seront générés. Il existe diverses autres spécifications comme indiqué dans la figure ci-dessus.
Cliquez sur OK une fois que tous les paramètres sont spécifiés.
- Nous pouvons maintenant voir le processus de génération de Java Doc dans la fenêtre de sortie. Un exemple de fenêtre de sortie Java Doc se présente comme indiqué ci-dessous:
- Une fois la génération terminée, les fichiers suivants sont générés.
- Comme nous avons spécifié la classe Main, le fichier Main.html est généré. Notez que l'index.html a également le même contenu que Main.html.
- Le fichier help-doc.html contient des définitions générales des entités Java. Un échantillon du contenu de ce fichier est présenté ci-dessous.
- De même, vous trouverez ci-dessous un exemple de contenu dans le fichier Main.html
C'est ainsi que nous pouvons générer de la documentation à l'aide de cet outil dans IntelliJ idea. Nous pouvons suivre des étapes similaires dans d'autres IDE Java comme Eclipse et / ou NetBeans.
Questions fréquemment posées
Q # 1) Quelle est l'utilisation de JavaDoc?
Répondre: L'outil JavaDoc est fourni avec JDK. Il est utilisé pour générer la documentation de code pour le code source Java au format HTML. Cet outil nécessite que les commentaires dans le code source soient fournis dans un format prédéfini comme /**….*/. Ceux-ci sont également appelés commentaires doc.
Q # 2) Quel est l'exemple de documentation Java?
Répondre: L'outil de documentation Java Doc génère des fichiers HTML afin que nous puissions afficher la documentation à partir du navigateur Web. Le véritable exemple en direct de la documentation JavaDoc est la documentation des bibliothèques Java d'Oracle Corporation, http://download.oracle.com/javase/6/ docs /Feu/.
Q # 3) Les méthodes privées ont-elles besoin de JavaDoc?
Répondre: Non. Les champs et méthodes privés sont réservés aux développeurs. Il n'y a aucune logique à fournir de la documentation pour les méthodes ou les champs privés qui ne sont pas accessibles à l'utilisateur final. Java Doc ne génère pas non plus de documentation pour les entités privées.
questions d'entrevue de services Web pour expérimentés
Q # 4) Qu'est-ce que la commande JavaDoc?
Répondre: Cette commande analyse les déclarations et les commentaires doc dans les fichiers source Java et génère les pages de documentation HTML correspondantes contenant la documentation des classes publiques et protégées, des classes imbriquées, des constructeurs, des méthodes, des champs et des interfaces.
Cependant, JavaDoc ne génère pas de documentation pour les entités privées et les classes internes anonymes.
Conclusion
Ce didacticiel décrit l'outil JavaDoc fourni avec JDK qui est utile pour générer la documentation du code pour le code source Java au format HTML. Nous pouvons générer de la documentation en exécutant la commande Java Doc via l'outil de commande ou en utilisant la fonctionnalité JavaDoc intégrée disponible dans la plupart des IDE Java.
Nous avons vu comment nous pouvons utiliser l'outil avec IntelliJIdea Java IDE pour générer de la documentation. Le didacticiel a également expliqué diverses balises pouvant être utilisées avec des commentaires de doc afin que l'outil puisse générer une documentation conviviale détaillant toutes les informations liées au code source.
=> Visitez ici pour apprendre Java à partir de zéro.
lecture recommandée
- Principes de base de Java: syntaxe Java, classe Java et principaux concepts Java
- Déploiement Java: création et exécution d'un fichier JAR Java
- Machine virtuelle Java: comment JVM aide à exécuter une application Java
- Tutoriel JAVA pour les débutants: plus de 100 tutoriels vidéo Java pratiques
- Classe Java Integer et Java BigInteger avec exemples
- Composants Java: plateforme Java, JDK, JRE et machine virtuelle Java
- Comment créer une documentation API dans Postman?