JSDoc注释规范是什么

小编给大家分享一下JSDoc注释规范是什么,相信大部分人都还不怎么了解,因此分享这篇文章给大家参考一下,希望大家阅读完这篇文章后大有收获,下面让我们一起去了解一下吧!

成都创新互联于2013年开始,先为白朗等服务建站,白朗等地企业,进行企业商务咨询服务。为白朗企业网站制作PC+手机+微官网三网同步一站式服务解决您的所有建站问题。

什么是 JSDoc

JSDoc 是一个根据 JavaScript 文件中注释信息,生成 JavaScript 应用程序或模块的API文档的工具。你可以使用 JSDoc 标记如:命名空间,类,方法,方法参数等。从而使开发者能够轻易地阅读代码,掌握代码定义的类和其属性和方法,从而降低维护成本,和提高开发效率。

JSDoc 注释规则

JSDoc注释一般应该放置在方法或函数声明之前,它必须以/ **开始,以便由JSDoc解析器识别。其他任何以  /*  ,  /***  或者超过3个星号的注释,都将被JSDoc解析器忽略。如下所示:

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

JSDoc 的注释效果

假如我们有一段这样的代码,没有任何注释,看起来是不是有一定的成本。

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

如果使用了 JSDoc 注释该代码后,代码的可阅读性就大大的提高了。

/**
* 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明确一个函数是某个类的构造函数。

@param 参数注释

我们通常会使用@param来表示函数、类的方法的参数,@param是JSDoc中最常用的注释标签。参数标签可表示一个参数的参数名、参数类型和参数描述的注释。如下所示:

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

@return 返回值注释

@return表示一个函数的返回值,如果函数没有显示指定返回值可不写。如下所示:

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

@example 示例注释

@example通常用于表示示例代码,通常示例的代码会另起一行编写,如下所示:

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

其他常用注释

@overview对当前代码文件的描述。

@copyright代码的版权信息。

@author  []代码的作者信息。

@version当前代码的版本。

以上是“JSDoc注释规范是什么”这篇文章的所有内容,感谢各位的阅读!相信大家都有了一定的了解,希望分享的内容对大家有所帮助,如果还想学习更多知识,欢迎关注创新互联行业资讯频道!


网站标题:JSDoc注释规范是什么
URL网址:http://pwwzsj.com/article/ppsdic.html