JSDoc 生成API文档（搭建及使用示例）

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

结果