Qu'est-ce que JSDoc ? Introduction aux spécifications d'annotation JSDoc

Le contenu de cet article porte sur qu'est-ce que JSDoc ? L'introduction des spécifications d'annotation JSDoc a une certaine valeur de référence. Les amis dans le besoin peuvent s'y référer, j'espère que cela vous sera utile.

Qu'est-ce que JSDoc

JSDoc est un outil qui génère une documentation API pour les applications ou modules JavaScript en fonction des informations d'annotation dans les fichiers JavaScript. Vous pouvez utiliser des balises JSDoc telles que : espace de noms, classe, méthode, paramètres de méthode, etc. Cela permet aux développeurs de lire facilement le code et de maîtriser les classes définies par le code ainsi que leurs propriétés et méthodes, réduisant ainsi les coûts de maintenance et améliorant l'efficacité du développement.

Règles de commentaire JSDoc

Les commentaires JSDoc doivent généralement être placés avant une déclaration de méthode ou de fonction, et ils doivent commencer par /** afin d'être reconnus par le JSDoc analyseur. Tout autre commentaire commençant par /* , /*** ou avec plus de 3 astérisques sera ignoré par l'analyseur JSDoc. Comme indiqué ci-dessous :

/*
**一段简单的 JSDoc 注释。
*/

L'effet commentaire de JSDoc

Si nous avons un morceau de code comme celui-ci sans aucun commentaire, il semble qu'il y ait un certain coût.

functionBook(title, author){
      this.title=title;
      this.author=author;
}
Book.prototype={
      getTitle:function(){
        returnthis.title;   
      },
setPageNum:function(pageNum){
      this.pageNum=pageNum;   
}
};

Si vous utilisez JSDoc pour annoter le code, la lisibilité du code sera grandement améliorée.

/**
* Book类，代表一个书本.
* @constructor
* @param {string} title - 书本的标题.
* @param {string} author - 书本的作者.
*/
functionBook(title, author){
    this.title=title;
    this.author=author;
}
Book.prototype={
/**
* 获取书本的标题
* @returns {string|*} 返回当前的书本名称
*/
getTitle:function(){
    returnthis.title;   
},
/**
* 设置书本的页数
* @param pageNum {number} 页数
*/
setPageNum:function(pageNum){
    this.pageNum=pageNum;   
}
};

@constructor Annotation de déclaration du constructeur

@constructor indique clairement qu'une fonction est un constructeur d'une certaine classe.

Annotation des paramètres @param

Nous utilisons généralement @param pour représenter les paramètres des fonctions et des méthodes de classe. @param est la balise d'annotation la plus couramment utilisée dans JSDoc. Les étiquettes de paramètre peuvent représenter le nom du paramètre, le type de paramètre et les commentaires de description du paramètre. Comme indiqué ci-dessous :

/**
* @param {String} wording 需要说的句子
*/
functionsay(wording){
    console.log(wording);
}

@return Annotation de la valeur de retour

@return indique la valeur de retour d'une fonction si la fonction n'affiche pas la valeur de retour spécifiée. , il n'est pas nécessaire de l'écrire. Comme indiqué ci-dessous :

/*
* @return {Number} 返回值描述
*/

@example Exemple de commentaire

@example est généralement utilisé pour représenter un exemple de code. Habituellement, l'exemple de code sera écrit sur une ligne séparée. , comme suit Affichage :

/*
* @example
* multiply(3, 2);
*/

Autres commentaires courants

@aperçu de la description du fichier de code actuel.

@copyrightInformations de copyright du code.

@author [] Informations sur l'auteur du code.

@version La version du code actuel.

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!