JS Doc3 生成API文档步骤。
一、安装node.js。
具体安装步骤参照如下网址：https://www.runoob.com/nodejs/nodejs-install-setup.html
二、安装JS Doc3。
1、安装好node.js之后，WIN+R => CMD打开命令窗口,输入以下命令：npm install jsdoc -g，然后ENTER运行，
2、出现如下提示，说明安装成功（JSDoc路径默认在命令窗口所在路径下的node_modules文件夹中。如我的命令窗口路径是
C:\Users\24623 ,那么JSDoc的安装路径即为C:\Users\24623\node_modules）。
3、将JSDoc的路径加到环境变量PATH中，如我的路径为C:\Users\24623\node_modules\.bin
4、添加成功后在命令窗口输入jsdoc-v 测试，如果能出现以下版本号相关信息，说明配置成功。
三、安装Docstrap。
1、打开命令窗口，输入npm i ink-docstrap，回车运行。
2、当出现以下信息，说明安装成功。
3、安装目录在命令窗口所在路径下的node_modules文件夹中的ink-docstrap文件夹中，如我的安装目录为C:\Users\24623\node_modules\ink-docstrap
四、整合JS Doc3和Docstrap。
1、整合配置文件。把JS Doc3安装目录中的jsdoc /conf.json.EXAMPLE文件和Docstrap安装目录中的jsdoc.conf.json文件都打开。
2、两个配置文件中有重合的部分，也有各自独立的部分，将两个文件内容整合到一起（可以新建一个json文件来存放整合后的配置信息）
整合前：
整合后：
3、整合后的文件里我添加了运行参数的配置信息，其中：template需要配如下路径，以node_modules/.bin文件夹中为基准路径。这里由于ink-docstrap文件夹和node_modules是同级，所以前面加上../，其余路径以此类推。destination属性指向输出目录，也是以node_modules/.bin文件夹中为基准路径。如不填写，则默认生成在node_modules/.bin/out文件夹中。readme是API首页内容信息。如不需要编写首页内容信息，则可屏蔽该属性；不屏蔽该属性的话则必须要指定该文件路径且该文件必须存在。
上面配置文件及详细注释见附件
4、如果要给多个文件批量生成API文档，则需要在上述配置文件中的source.include属性中配置文件路径，也是以node_modules/.bin文件夹中为基准路径。
五、运行JS Doc.
1、首先打开命令窗口，然后通过cd 命令进入到node_modules/.bin路径下，然后运行如下命令：
jsdoc -c ../jsdoc.conf.json
2、注意：这里的-c 意思是执行指定的配置文件；-c后面跟的是 空格+配置文件的路径。这里的jsdoc.conf.json就是我上面整合在一起的配置文件。（需要生成API的代码文件需要与上面配置文件jsdoc.conf.json中source.include属性中指定的文件名和路径一致）
运行成功后如下所示。
3、然后打开输出目录（我的输出目录指定的是node_modules/.bin/docs），可见api文件均已生成。
4、打开index.html即可查看详细的API文档信息。
六、API皮肤更换。
1、Api的皮肤控制是在配置文件中控制的，控制字段为theme,如下：
2、只要更改theme的值，然后重新生成一次API文档即可。
3、各个字段对应的皮肤效果见附件：皮肤.zip
七、JSDoc3常用代码注释说明。
1、@class.
描述：此函数旨在需要使用"new"关键字调用，即构造函数。
别名: @constructor
Overview（概述）
@class标签标明函数是一个构造器函数，意味着需要使用 new 关键字来返回一个实例，即使用 new 关键字实例化。
注意：@class后面的名称需要和类名保持一致，否则无法匹配其内部声明的变量和方法。如下：
2、@description
描述: 描述一个标识.
别名: @desc
Overview（概述）
@description标签允许您提供一般描述。该说明可能包括HTML标签。如果Markdown 插件启用 的 话，它也可包括Markdown格式。
3、@function
描述: 描述一个函数或方法。
别名: @func @method
Overview（概述）
标记一个对象作为一个函数，即使它可能不会出现在解析器中。它设置doclet的@kind为'function'。
4、@param
描述: 记录传递给一个函数的参数。
别名: arg argument
概述
@param标签提供了对某个函数的参数的各项说明，包括参数名、参数数据类型、描述等。
@param标签要求您指定要描述参数的名称。您还可以包含参数的数据类型，使用大括号括起来，和 参数的描述。
参数类型可以是一个内置的JavaScript类型，如string或Object，或是你代码中另一个标识符的JSDoc namepath（名称路径）。如果你已经在这namepath（名称路径）上为标识符添加了描述，JSDoc会 自动链接到该标识符的文档。您还可以使用type的表达式来表示，例如，该参数不能为空或可以接受 任何类型;详见@type 标签文档。
如果您提供的描述，在描述之前插入一个连字符，可以使JSDoc注释更具可读性。请务必在连字符后 加一个空格。
5、@returns
描述: 记录一个函数的返回值。
别名:return
概述
@returns 标签描述一个函数的返回值。语法和@param类似。
6、@author
指定项目的作者；
Overview（概述）
@author标签标识一个项目的作者。在JSDoc3.2和更高版本中，如果作者的名字后面跟着尖括号括 起来的电子邮件地址，默认模板将电子邮件地址转换为mailto:链接。
7、@callback
描述一个回调函数。
Overview（概述）
描述一个回调函数。@Callback标签提供回调函数（可传递给其他函数）的描述，包括回调的参数和 返回值。你可以包涵任何一个你能提供给@method标签。
一旦你定义了一个回调，你可以像@typedef标签所定义的自定义类型那样使用它。尤其是，你可以 使用回调的名称作为类型名称。这样您可以使你明确指明函数参数应包含那个回调。
如果你想要一个回调显示为某个特定类的类型定义，可以给回调加一个namepath，指示它是某个类 的一个内部函数。您还可以定义一个引用多个类引用的全局的回调类型。
8、@version
描述: 描述版本信息。
概述
@version标签后面的文本将被用于表示该项的版本。
9、@static
描述: 记录一个静态成员。
概述
@static标签标明一个在父类中的标识符不需实例即可使用。
使用@static标签将重写标识符的默认作用域，但有一个例外：在全局作用域下的标识符将保持他的 全局性。
10、@augments
指名这个子类继承至哪个父类，后面需要加父类名
别名：@extends
Overview（概述）
@augments or@extends标签指明标识符继承自哪个父类，后面需要加父类名。你可以使用这个标签 来记录基于类和并基于原型的继承。
在JSDoc3.3.0或更高版本中，如果一个标识符继承自多个父类，并且多个父类有同名的成员，JSDoc 使用来自列出的JSDoc注释中最后一个父类的文档。
网友评论