关于HTML帮助文档翻译,JSDoc中文文档（翻译）

什么是JSDoc

JSDoc是一个根据javascript文件中注释信息，生成JavaScript应用程序或库、模块的API文档 的工具。你可以使用他记录如：命名空间，类，方法，方法参数等。类似JavaDoc和PHPDoc。现在很多编辑器或IDE中还可以通过JSDoc直接或使用插件生成智能提示。从而使开发者很容易了解整个类和其中的属性和方法，并且快速知道如何使用，从而提高开发效率，降低维护成本。

使用JSDoc

JSDoc本质是代码注释，所以使用起来非常方便，但是他有一定的格式和规则，只要了解这些，那么后面的事情，比如生产文档，生成智能提示都可以通过工具来完成。

JSDoc注释

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

/**

* Book类，代表一个书本.

* @constructor

* @param {string} title - 书本的标题.

* @param {string} author - 书本的作者.

*/

function Book(title, author) {

this.title=title;

this.author=author;

}

Book.prototype={

/**

* 获取书本的标题

* @returns {string|*}

*/

getTitle:function(){

return this.title;

},

/**

* 设置书本的页数

* @param pageNum {number} 页数

*/

setPageNum:function(pageNum){

this.pageNum=pageNum;

}

};

JSDoc注释标签

看了上面的代码注释是不是一目了然呢，获取你会疑惑上面以@开头的标签是什么意思。

在JSDoc 注释有一套标准的注释标签，一般以@开头。这里解释一下每个标签的意思。

关于别名

因为JSDoc也经历好几个版本，所以考虑向后兼容，所以存在别名，另一个方面，别名对于一部分人来说更加直观。

比如@param有两个别名：

@arg

@argument

关于别名详细说明可以查看上面描述。

JSDoc注释标签的使用