Introduction à la spécification javadoc

Introduction :

Nous savons que javadoc est intégré dans le JDK, donc suivre la spécification javadoc est définitivement l'orthodoxie de l'annotation java. Avec l'aide de javadoc, c'est. est nécessaire pour générer la documentation API Très pratique.

(Partage de vidéos d'apprentissage : tutoriel vidéo Java)

1. Que sont les commentaires

Les commentaires sont à faire ? coder plus Il est lisible et réduit le coût de communication du travail d'équipe. Dans une équipe, si votre code est plus clair, plus lisible et plus standardisé, alors la promotion et l'augmentation de salaire seront définitivement les vôtres, car vous pourrez être compatible avec plus de personnes.
J'ai entendu un dicton il y a quelque temps : si vous êtes le seul à pouvoir comprendre votre code, alors vous êtes la personne indispensable. La personne qui a dit cela est stupide. Lui seul peut comprendre le code qu'il écrit. Personne ne veut le voir. Il vit comme un petit-fils.

2. Touches de raccourci de commentaire couramment utilisées

Commenter une ligne : //Je suis le contenu de la ligne
Touche de raccourci : ctrl+/ Opération inverse : ctrl+/Commenter un bloc : / *Je suis le contenu du bloc* /
Touche de raccourci : ctrl+shift+/ Opération inverse : ctrl+shift+javadoc Commentaires reconnaissables :

	/**
	 * 我是注释
	 * 我也是注释
	 * 我还是注释，我们都能被javadoc识别
	 */

3. Spécification Javadoc

Suivez la spécification javadoc, nous pouvons utiliser la commande javadoc pour générer des documents API très intuitifs et faciles à lire, ce qui est très pratique.
Les commentaires que nous apparaissons dans le programme peuvent être consciemment divisés en deux types, l'un est constitué de commentaires simples, pour notre propre lecture, et l'autre est constitué de commentaires conformes à la spécification javadoc, dans le but de générer des commentaires faciles à lire. documents.
Lisez attentivement le document API généré. Il y a trois parties que nous devons expliquer, comme le montre la figure :

Le contenu dans la case rouge ci-dessus est les commentaires que j'ai ajoutés. C'est un simple cours Hello. Le code source est le suivant. Si vous êtes intéressé, vous pouvez l'essayer vous-même :

.

/**
  *	@author XXXX
  *	@version 创建时间：2021年1月21日 下午3:22:01
  *	
  */
public class Hello {

	/**
	 * main()方法简述(后面这个dot必不可少).
	 * <p>这就是为了测试注释<br>
	 * 没什么好说明的，只为了说明能出现在这里
	 * @param args 就是系统配的，没啥说的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}
	
	/**
	 * havaReturn方法就是为了测试javadoc注释规范的.
	 * <p>我发现只有有返回值的方法才可以使用return标签<br>
	 * 没有return硬是要用，只会在javadoc时候报错
	 * @param a 输入的第一个int类型的参数
	 * @param b 输入的第二个int类型的参数
	 * @return add 两个数的和运算结果
	 */
	public int haveReturn(int a,int b){
		int add=0;
		add=a+b;
		return add;
	}

}

Il y a plusieurs points à souligner :

Si vous souhaitez que l'auteur et la version apparaissent dans le document API, vous ne devez pas seulement ajouter @author et @version dans les commentaires du programme ( il est à noter que l'annotation de @author à plusieurs endroits dans le programme ne sera affichée qu'une seule fois dans le document final (je recommande de ne commenter qu'une seule fois), et de le signaler également dans la commande dos lors de la compilation :
dossier javadoc -d. -version -author Hello.java
où -d dossier signifie que vous placez le document API généré (en fait de nombreuses pages Web composées) est placé dans un dossier dossier Bien sûr, le dossier peut également être un chemin

Comment faire la distinction entre le résumé de la méthode et les détails de la méthode ?

/**
	 * main()方法简述(后面这个dot必不可少).
	 * <p>这就是为了测试注释<br>
	 * 没什么好说明的，只为了说明能出现在这里
	 * @param args 就是系统配的，没啥说的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}

Vous avez dû constater qu'il y a beaucoup de commentaires sur les méthodes Comment extraire le résumé de javadoc ? C'est vrai, comptez simplement sur un point (.), observez le point mentionné dans mon commentaire, c'est la clé pour extraire le résumé. Le point est précédé du résumé, et tout est une introduction détaillée (l'introduction détaillée inclut le résumé. )

Comment contrôler la composition des commentaires dans les documents générés

Ce que nous pouvons contrôler dans le programme, c'est la composition des commentaires, mais cette composition n'est pas reconnue par Javadoc qui trouve une ligne de commentaires et uniquement. supprime * et les espaces. , je viens de le passer et j'ai remarqué que le document généré est de type HTML, donc tant que vous commentez la syntaxe HTML dans le programme, vous pouvez modifier le format du document API. trop difficile, car nous utilisons simplement une syntaxe HTML simple, comme les paragraphes

, la nouvelle ligne
, cela suffit, après tout, les commentaires ne seront pas très longs.

Description du paramètre @param 1 (notez le format)

@description de la valeur de retour (notez le format)

Écrivez-la s'il y a une valeur de retour S'il n'y a pas de valeur de retour. , vous n'avez pas besoin de l'écrire. Si vous l'écrivez, ce sera le cas. Signalement des erreurs

En fait, écrire des commentaires de classe et des commentaires de méthode est très simple. Tapez simplement /** devant la classe et la méthode. , puis appuyez sur Entrée, le système l'ajoutera automatiquement et nous pourrons modifier la façon dont le système l'ajoute

Comment modifier le contenu qui apparaît lors de la création d'un nouveau fichier, comment faire les commentaires d'auto-complétion sous notre contrôle (à faire)

Nous voyons cela dans le fichier de classe standard :

Nous savons tous que out est un attribut (champ) du Classe système, qui est de type PrintStream. Il existe de nombreuses méthodes définies dans la classe PrintStream. Ce sont naturellement des méthodes out, donc lors de la définition de out , il y a beaucoup de @see dans les commentaires devant. pour utiliser l'annotation @see Nous recommandons que lors de la définition des champs d'une classe, si le champ est un type composite (en particulier un type composite personnalisé), alors notez @see devant, cela présente deux avantages, veuillez voir l'image :

Je pense que vous connaissez ces deux images. La première est une invite qui peut apparaître lorsque le curseur reste lors de l'écriture d'un programme. Si vous écrivez des commentaires selon la spécification javadoc, alors vous l'avez écrit vous-même. Le programme apparaît également avec ces invites extrêmement utiles. La seconde est la description détaillée du champ out dans la classe String dans le document API Java8. C'est également le mérite de @see. Vous avez écrit @see, et il existe une telle annotation dans votre propre document API de projet.

Recommandations associées : Tutoriel d'introduction à Java

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!