jsdoc文档生成
# 如何使用基于node.js的JSDoc制作自己写的mv项目插件代码的API网页版说明文档
在插件开发中,我们会写出很多的代码。为了使其他人更好地阅读我们的代码,除了在代码中写上注释,还有生成API接口文档
的方式来帮助他人阅读代码。对于JavaScript
这种弱类型的语言来说,就更需要写注释了。对于mv
项目来说,大部分的插件代码都没有写注释,那我们要本着负责的态度,对自己的代码负责,就更需要写清楚自己代码的注释。
# jsdoc是什么?
在生成API
接口文档之前,我们要先了解JSDoc
是什么?JSDoc
不仅是一个API接口生成工具,更是一种注释语法,它类似于JavaDoc
,更确切地讲,JSDoc
就是从JavaDoc
引申而来的。在使用JSDoc
工具之前,我们要先学会其注释语法。事实上,VScode
本身就自动对JavaScript
支持JSDoc
,学习成本会大幅下降。
点此阅读JSDoc在线手册 (opens new window)
在CSDN
中,绝大多数的JSDoc
使用教程都在使用极其熟悉的npm
包导入方式,要想使用npm
,就必须先安装node环境 (opens new window)。安装完node
环境后,JSDoc的安装和使用 (opens new window)就极其容易了。
# 配置环境
关于node
安装,建议读者自行去CSDN (opens new window)查询关于node
环境的安装配置教程。
# 安装node环境 不严谨
去node官网 (opens new window)下载windows installer
版本的安装包。
# 配置npm 不严谨
在你的nodejs
目录下创建两个目录,分别是node_cache
和node_global
。在cmd
执行下面这两个命令:
npm config set prefix '你的安装位置\nodejs\node_global'
npm config set cache '你的安装位置\nodejs\node_cache'
2
# 配置环境变量 不严谨
在环境变量的配置界面配置NODE_PATH
,值填:你的安装位置\nodejs\node_global\node_modules
修改Path
中含有npm
值的式子,修改为:你的安装位置\nodejs\node_global\
# 使用全局的jsdoc 不推荐
# 安装jsdoc
在cmd
输入以下命令安装jsdoc
npm install -g jsdoc
如果你没有配置好本地npm
的全局包储存位置,那么全局安装的包总是会自动储存到C盘,这很容易让你的C盘爆满。请不要高估C盘的承载能力,也不要随意地使用全局安装,除非你已经确定将npm
的本地仓库配置到了非C盘的位置。
# 使用jsdoc命令
找到自己写插件代码所储存的上一层级文件夹目录,在此目录中打开cmd
。在此cmd
中输入以下命令。
jsdoc -r 文件夹名称
# 阅览生成的文档
在新生成的out
文件夹内点击index.html
文件即可检查自己所写插件代码的API接口文档
。
# 使用局部的jsdoc 推荐
相比于全局的jsdoc
,作者跟建议大家使用局部的jsdoc
。jsdoc
其本质是一个文档生成工具,没必要安装为全局包,安装为项目的局部开发环境依赖包即可。
以下的内容更加倾向于专业开发者阅读,如果你在阅读的时候遇到障碍,你可能需要去了解学习关于node
环境、npm
以及依赖包
等相关概念。
# 前提
此时,我们总是默认当前项目为标准的node
项目,如果你已经配置好了本机的node
环境,请在你的mv
工程下使用npm init
命令来初始化一个node
项目。你可以理解为把mv
项目拓展为node
项目,而不是node
项目覆盖了你的mv
项目。
# 局部安装开发环境的jsdoc
npm install --save-dev jsdoc
这行命令与上述的全局安装命令有着很大的区别,请读者自行去查阅npm
命令参数-g
与--save-dev
之间的差别。
# 在项目根目录下配置conf.json文件
在项目根目录下新建conf.json
并配置。本文不提供细致的配置教程,点此参考conf.json
的配置写法 (opens new window)。配置参考如下:
{
"tags": {
"allowUnknownTags": true,
"dictionaries": [
"jsdoc",
"closure"
]
},
"source": {
"include": [
"sourceCodeFile"
],
"exclude": [],
"includePattern": ".+\\.js(doc)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"plugins": [],
"templates": {
"cleverLinks": false,
"monospaceLinks": false
},
"opts": {
"template": "templates/default", // same as -t templates/default
"encoding": "utf8", // same as -e utf8
"destination": "rpgmv-api-doc",
"recurse": true // same as -r
// "tutorials": "path/to/tutorials" // same as -u path/to/tutorials
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# 执行jsdoc命令并在指定文件夹内生成出api文档
推荐默认在根目录下执行jsdoc
命令:
node ./node_modules/jsdoc/jsdoc.js -c conf.json
上述命令行的配置写法参考于此文章 (opens new window)。此时生成的静态网页在rpgmv-api-doc
文件夹内,因为作者在conf.json
内的destination
配置项中指明了输出文件夹目录。
# jsdoc的高阶配置 进阶
本节内容展示的是进阶版本jsdoc
配置,默认你已经阅读完了上述的全部内容。本节内容几乎就是为了给专业程序员阅读的,如果你本身没有相当过硬的基础,这些内容对你来说属于天书,请不要在此浪费时间。
默认你具有这样的基础或能力
- 翻墙阅览
github
仓库 - 能够阅读简单的纯英文
API
文档
# 参考资料
# 使用更加易于配置的.js格式替代.json格式的配置文件
此文档 (opens new window)指出,高版本以上的jsdoc
是支持CommonJS module
模块的,参照文档要求自行改造配置文件即可。页面如下图:
作者的可参考写法如下:
'use strict';
module.exports = {
tags: {
allowUnknownTags: true,
dictionaries: ['jsdoc', 'closure'],
},
source: {
include: ['sourceCodeFile'],
exclude: [],
includePattern: '.+\\.js(doc)?$',
excludePattern: '(^|\\/|\\\\)_',
},
plugins: [],
templates: {
cleverLinks: false,
monospaceLinks: false,
// 使用主题插件 better-docs 的名称配置
'better-docs': {
name: '阮中楠文档',
},
// 使用主题插件 tui-jsdoc-template 的配置
name: '阮中楠的文档',
footerText: '底部导航栏文字',
},
opts: {
/**
* 可用的一些模板 需要自行安装下载 自行去github搜索相关细节
* templates/default
* node_modules/minami
* node_modules/better-docs
* node_modules/tui-jsdoc-template
*/
template: 'node_modules/tui-jsdoc-template',
encoding: 'utf8',
destination: 'rpgmv-api-doc',
recurse: true,
readme: './README.md',
verbose: true,
// "tutorials": "path/to/tutorials"
},
};
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# 使用新的命令行来生成文档
node ./node_modules/jsdoc/jsdoc.js -c jsdoc.js
# 使用更加炫酷的主题插件
jsdoc
作为一款文档自动化生成工具,自然是可以配置文档主题的。文档主题样式同样以node
包安装。这里不介绍如何配置。
点此查阅如何在jsdoc配置文件中配置主题插件 (opens new window)。
点此查阅官方推荐的一些主题插件 (opens new window)。
# 主页的readme.md文档配置
自动生成的文档主页一般总是配置成项目的readme.md
文件,使用以下配置即可引用文档:
opts: {
readme: './README.md'
}
2
3