Comment générer de la documentation à l'aide des commentaires de la documentation Java ?

Nous savons que Java prend en charge 3 types de commentaires, à savoir les commentaires sur une seule ligne, les commentaires sur plusieurs lignes et les commentaires sur les documents. Voyons à quoi ils ressemblent

//Commentaires sur une seule ligne

/*
Multi-. commentaires en ligne
*/

/ **
*@...
*....
*Commentaires sur la documentation
*/

Peut-être que beaucoup de débutants ne comprennent pas, à quoi ça sert d'écrire ces commentaires ?

En fait, c'est parce que les débutants disposent d'une petite quantité de code et peuvent le rechercher et le modifier rapidement sans commentaires.

Lorsque le code s'agrandit progressivement, les commentaires sont une bonne chose, non seulement pour eux-mêmes pour voir le code clairement, mais aussi. aussi dans un souci de communication avec les autres. Une commodité pour les membres qui développent des projets avec vous

N'oubliez pas, débarrassez-vous de cette mauvaise habitude de ne pas écrire de commentaires ! ! !

Alors voici notre sujet d'aujourd'hui, que sont les commentaires Doc ?

Javadoc est une technologie fournie par Sun. Elle extrait des commentaires tels que les classes, les méthodes, les membres, etc. du code source du programme pour former un document d'aide API qui correspond au code source. En d'autres termes, tant que vous utilisez un ensemble spécifique de balises comme commentaires lors de l'écriture d'un programme, une fois le programme écrit, la documentation de développement du programme peut être formée en même temps via Javadoc.

La commande javadoc est utilisée pour générer des documents API. Comment l'utiliser : Utilisez la ligne de commande pour saisir javadoc + nom du fichier.java dans le répertoire où se trouve le fichier cible

Vous n'avez pas besoin de vous emmêler. ces théories compliquées. Il faut cultiver une sorte de pensée pour comprendre, comprendre, approfondir, la changer, la comprendre, et s'accrocher à la théorie n'aura aucun effet !

Lorsque nous écrivons du code, il existe des normes. Si le code que vous écrivez peut s'exécuter, mais qu'il est en désordre, personne n'est disposé à l'utiliser car il est difficile à maintenir. Par conséquent, le code n'est pas qu'un simple programme. dans le monde en ligne, je préfère l'appeler une œuvre d'art, qui nécessite votre gravure soignée

Certaines personnes diront, n'est-ce pas juste une annotation ? Quel est le problème avec ça

Cependant, ce commentaire Doc n'est pas le même que les deux autres commentaires. Il existe également des normes pour les commentaires !

Spécifications des annotations de documents

Format :

Les annotations de documents écrites sur les classes sont généralement divisées en trois paragraphes :

Premier paragraphe : Description sommaire, généralement une phrase ou un paragraphe pour décrire brièvement la fonction de la classe, avec un point en anglais comme fin

Deuxième paragraphe : Description détaillée, généralement un ou plusieurs paragraphes sont utilisés pour décrire la fonction de la classe en détail. Généralement, chaque paragraphe se termine par un point anglais

Troisième paragraphe : Annotation du document, utilisée pour marquer l'auteur. et le temps de création, les classes de référence et d'autres informations

Ici, je souhaite approfondir un peu mes connaissances. Nos commentaires Doc peuvent utiliser des commandes Dos ou des outils IDE pour générer un document Doc. Ce document est exécuté via le langage HTML, donc certains codes HTML simples peuvent le faire. être utilisé dans les commentaires, comme le suivant

saut de ligne

paragraphe

(écrit avant le paragraphe)

Mettez un exemple de diagramme de style :

L'utilisation du symbole @

Nous écrivons Doc Lorsque vous commentez, appuyez sur Entrée directement après /**, et le cadre de commentaire suivant et certains symboles @ seront automatiquement générés. Alors, à quoi servent ces symboles @ ?

{@link}Décrit les paramètres d'une méthode, généralement utilisés pour les commentaires de méthodeDécrit le type de valeur de retour, généralement utilisé pour les commentaires de méthode, Ne peut pas apparaître dans la méthode de constructionSpécifiez un lien vers un autre sujetDécrit un attribut de sérialisationDécrit les données écrites via les méthodes writeObject() et writeExternal() Décrit un ObjectStre Composant amFieldIndiquez dans quelle version cette fonction se trouve depuis est la même que la balise @exception.Affiche la valeur d'une constante, qui doit être un attribut statique. Spécifie la version de la classe, généralement utilisée pour les annotations de classe@La partie I J'ai ici En anglais, vous pouvez écrire en chinois, comme @author XiaojianComment générer un document DocNous avons dit plus haut qu'après avoir écrit des commentaires Doc, un document Doc peut être généré, et il est au format HTML, donc comment le générer ? Premier : Génération de commandes Dos javadoc [options] [packagenames] [sourcefiles]

tag	description	exemple
@author	identifie l'auteur d'une classe, généralement utilisé pour les annotations de classe	@author description
@deprecated	désigne une classe ou un membre expiré , indiquant que l'utilisation de la classe ou de la méthode n'est pas recommandée	@deprecated description
{@docRoot}	Indique le chemin d'accès au répertoire racine actuel du document	Chemin du répertoire
@exception	Une description de l'exception qui peut être levée, Généralement utilisé pour les commentaires de méthode	@exception exception-name explication
{@inheritDoc}	Hérite d'un commentaire de la surperclasse immédiate.
Insère un lien en ligne Insère un lien en ligne vers un autre sujet.		@param
@param paramètre-nom explication		@return
@explication de retour		@see
@voir ancre		@serial
@serial description		@serialData
@serialData description		@serialField
@serialField nom type description		@ depuis
@since release		@throws
La balise @throws a la même signification que la balise @exception.		{@value}
Affiche la valeur d'une constante, qui doit être un champ statique.		@version
@version info

Explication du format :

options représente les options de la commande Javadoc ; >packagenames représente le nom du package ;

sourcefiles représente le nom du fichier source

Vous pouvez le voir en entrant javadoc -help dans cmd (invite de commande) ) Utilisation et options de Javadoc (à condition que JDK soit installé et configuré), les options courantes de la commande Javadoc sont répertoriées ci-dessous :

Nom

Description

options 表示 Javadoc 命令的选项；

packagenames 表示包名；

sourcefiles 表示源文件名;

在 cmd（命令提示符）中输入javadoc -help

-publicAfficher uniquement les classes et les membres publics- protectedafficher les classes et les membres protégés/publics (par défaut)-packageafficher le package/protégé/classes et membres publics-privateafficher toutes les classes et les membres-d Répertoire de destination du fichier de sortie-versioncontient le segment @version-authorcontient le segment @author-splitindexse divise l'index dans chaque lettre correspondant à un fichier -windowtitle Le titre de la fenêtre du navigateur du document est gênant et lent à générer avec Doc. Existe-t-il une autre méthode ?

Deuxième : génération d'outils IDE	Nous pouvons utiliser Eclipse ou IDEA pour le générer. Je n'utilise pas beaucoup Eclipse. Laissez-moi vous le démontrer en utilisant IDEA !

Dans le JavaDoc de l'outil, cela ressemble à ceci après l'avoir saisi

Le répertoire de sortie doit être sélectionné, sinon il ne sera pas généré

Faites attention, car l'encodage de Java est différent de celui d'IDEA, donc dans les autres Dans la colonne paramètre de commande, vous devez renseigner le contenu suivant

-encoding utf8 -docencoding utf8 -charset utf8

Après génération, ça ressemble à ça

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!