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注释中最后一个父类的文档。
点我查看详细信息