jsDoc注释规范

最新推荐文章于 2024-08-15 09:39:40 发布

Sophie_U

最新推荐文章于 2024-08-15 09:39:40 发布

阅读量9.3k

点赞数 18

分类专栏：规范文档文章标签： javascript 前端开发语言

本文链接：https://blog.csdn.net/Sophie_U/article/details/124824990

版权

JSDoc 是一个用于JavaScript的API文档生成器，它根据代码中的注释生成文档。本文介绍了JSDoc的基本用法，如@constructor、@param、@return、@example等注释规范，以及如何通过JSDoc生成文档网站。同时，还展示了如何配置JSDoc以自定义输出和使用不同模板。

摘要由CSDN通过智能技术生成

jsDoc，顾名思义，jsDoc是一个用于JavaScript的API文档生成器，类似于Javadoc或phpDocumentor。它根据JavaScript文件中的注释信息，生成JS应用程序或模块的API文档。通过使用JSDoc标记如：命名空间，类，方法参数等，从而使开发者能够轻易地阅读代码，掌握代码定义的类和和其属性和方法，从而降低维护成本并提高开发效率。
JSDoc中文文档
 JSDoc官网
JSDoc注释通常应该放在代码被记录之前。为了被JSDoc解析器识别，每个注释必须以/**序列开头,以便由JSDoc解析器识别。

/**
** 这是一段简单的JsDoc注释。
*/

一、常用注释规范

1.1 @constructor 构造函数声明注释

@constructor明确一个函数是某个类的构造函数

1.2 @param 参数注释

通过@param来表示函数、类的方法的参数。@param是最常用的注释标签。参数标签可表示一个参数的参数名、参数类型和参数描述的注释。通过参数注释，可以在vscode中联想出相应的参数类型，让开发更便捷。如：

/**
* 表示一本书
* @constructor
* @param {
   string} title - 书名
* @param {
   string} author - 作者
*
*/
function Book(title,author){
   }

let book = new Book('aaa','bbb')

param {string} title ：表示给参数title增加一个string类型。这个类型可以是string,number,boolean这类基础数据类型，也可以是复杂数据类型如object

/**
 * 
 * @param {
   Object} book 
 * @param {
   string} book.title
 * @param {
   string} book.author
 */

function buyBook(book) {
       }

// 数组参数
/**
 * Assign the project to a list of employees.
 * @param {
   Object[]} employees - The employees who are responsible for the project.
 * @param {
   string} employees[].name - The name of an employee.
 * @param {
   string} employees[].department - The employee's department.
 */
Project.prototype.assign = function(employees) {
    // ...
}; 

// 可选参数
/**
 * @param {string} [somebody] - Somebody's name.
 */
function sayHello(somebody) {
   
    if (!somebody) {
   
        somebody