JSDoc工具
An API documentation generator for JavaScript.
Want to contribute to JSDoc? Please read CONTRIBUTING.md.
官方地址链接: JSDoc.
依照官方说明,JSDoc作为一个工具,其主要的功能就像其描述一样。
工具安装
在npm上全局安装最新版本(这里使用全局安装比较方便使用):
npm install -g jsdoc
工具运行
全局安装的JSDoc,请运行以下jsdoc命令:
jsdoc yourJavaScriptFile.js
默认情况下,生成的文档保存在名为的目录中out。
如果需要进一步的了解相关使用命令,运行jsdoc --help以获取命令行选项的完整列表。
JSDoc使用示例
依据相应的注释标记,JSDoc可以根据用户编写好的代码内容生成相应的使用文档。
示例
这里使用test.js作为示例进行说明
/**
* @fileOverview 用户信息描述
* @author Test
*/
/**
* @constructor UserInfo
* @description 自我介绍
* @see The <a href="https://blog.csdn.net">test</a >.
* @example new UserInfo();
*/
function UserInfo()
{
/**
* @description {String} 姓名
* @field
*/
this.Name = "test JSDoc";
/**
* @description 打招呼
* @param {String} title 说话标题
* @param {String} content 说话内容
* @return {Num} nResult 返回结果
*/
this.SayHello = function()
{
alert( arguments[0] + " my name is " + this.Name + arguments[1]);
}
}
注意事项
1、我们使用JSDoc生成javascriptAPI文档,必须要使用规范的注释。该注释可以参考 http://usejsdoc.org/.
2、为多个文件生成帮助文档,此时我们可以配置C:\Users\user\node_modules\jsdoc目录下的conf.json.EXAMPLE文件。为这个文件source里面添加一行如下图所示:
将要生成API文档的JS文件名称配置进入,然后将这写配置了的JS文件拷贝到C:\Users\user\node_modules.bin这个文件夹里面。在cmd里面运行jsdoc,即可生成API文档。
注意:
可能我们生成的API文档会有乱码,因为JSDoc生成的API文档默认是使用utf8编码格式生成文档。当我们的js文件内容不是使用utf8的时候,就会产生乱码。此时我们将JS文件都改成utf8编码,然后重新生成帮助文档,这样就不会有编码问题。
补充
你也许注意到了,没有一个根页面,因为jsDoc根据README.md文件来生成。
因此,我们添加一个。(这里如果你有安装touch工具的话)
touch README.md
并简单介绍一下,如果没有上面的工具,在目录下简单建立一个md文件即可
# 使用jdDoc来生成文档
## Hello World示例
这里是根页面
我们再次生成文档,注意第二个参数是README.md。
jsdoc test.js README.md