What is JSDoc? Introduction to JSDoc annotation specifications

The content of this article is about what is JSDoc? The introduction of JSDoc annotation specifications has certain reference value. Friends in need can refer to it. I hope it will be helpful to you.

What is JSDoc

JSDoc is a tool that generates API documentation for JavaScript applications or modules based on annotation information in JavaScript files. You can use JSDoc tags such as: namespace, class, method, method parameters, etc. This enables developers to easily read the code and master the classes defined by the code and their properties and methods, thereby reducing maintenance costs and improving development efficiency.

JSDoc comment rules

JSDoc comments should generally be placed before a method or function declaration, and it must start with /** in order to be recognized by the JSDoc parser. Any other comments starting with /* , /*** or with more than 3 asterisks will be ignored by the JSDoc parser. As shown below:

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

The comment effect of JSDoc

If we have a piece of code like this without any comments, it seems that there is a certain cost.

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

If you use JSDoc to annotate the code, the readability of the code will be greatly improved.

/**
* 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 Constructor declaration annotation

@constructor makes it clear that a function is the constructor of a certain class.

@param Parameter annotation

We usually use @param to represent the parameters of functions and class methods. @param is the most commonly used annotation tag in JSDoc. Parameter labels can represent a parameter's parameter name, parameter type, and parameter description comments. As shown below:

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

@return Return value comment

@return indicates the return value of a function. If the function does not display the specified return value, it does not need to be written. As shown below:

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

@example Example comment

@example is usually used to represent example code. Usually the code of the example will be written on a new line, as shown below:

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

Other common comments

@overview Description of the current code file.

@copyrightThe copyright information of the code.

@author [] Author information of the code.

@versionThe version of the current code.

The above is the detailed content of What is JSDoc? Introduction to JSDoc annotation specifications. For more information, please follow other related articles on the PHP Chinese website!