项目中使用到需要把js方法生成接口文档，使用到了 JS doc 这个工具，使用该工具生成文档，需要在方法里加入注释，根据注释说明生成文档，这里顺便记录一下使用过程,模拟了一些js，演示一些使用到的注释信息，更多注释信息说明具体可以查看官方文档。
站在用户的角度思考问题，与客户深入沟通，找到广安网站设计与广安网站推广的解决方案，凭借多年的经验，让设计与互联网技术结合，创造个性化、用户体验好的作品，建站类型包括：成都网站建设、成都网站制作、企业官网、英文网站、手机端网站、网站推广、域名与空间、虚拟空间、企业邮箱。业务覆盖广安地区。
官方：https://jsdoc.app/
中文文档：https://jsdoc.zcopy.site/
源码地址：https://gitee.com/mirrors/JsDoc3
# 全局安装
npm install -g jsdoc
# 本地安装
npm install --save-dev jsdoc
下面是 demo.js 样例
/**
* Book类
* @constructor
* @param {string} title - 书本的标题.
* @param {string} author - 书本的作者.
*/
function Book(title, author) {
this.title=title;
this.author=author;
}
/**
* 获取书本的标题
* @returns {string}
*/
Book.prototype.getTitle= function(){
return this.title;
}
/**
* 根据书本标题获取书本作者
* @param {String} title
*/
Book.prototype.getAuthor = function(title){}
/**
* 根据书本标题获取书本目录
* @param {String} title
*/
Book.prototype.getBookCatalog = function(title){}
/**
* 设置书本的页数
* @param {number} pageNum 页数
*/
Book.prototype.setPageNum = function(pageNum){
this.pageNum=pageNum;
}
/**
* 学生类
* @constructor
*/
function Student(){}
/**
* 创建学生信息
* @param {object} params
* @param {object[]} params.data - 信息数据
* @param {String} params.data.name - 姓名
* @param {number} params.data.age - 年龄
* @param {String} params.data.gender - 性别
* @param {String} params.data.class - 班级
* @param {number} params.data.studentId - 学号
* @param {function} [params.callbackFn=null] - 添加信息回调
*/
Student.prototype.create = function({data,callbackFun} = {}){}
/**
* 修改学生信息
* @param {object} params
* @param {object[]} params.data - 信息数据
* @param {String} params.data.name - 姓名
* @param {number} params.data.age - 年龄
* @param {String} params.data.gender - 性别
* @param {String} params.data.class - 班级
* @param {number} params.data.studentId - 学号
* @param {function} [params.callbackFn=null] - 添加信息回调
*/
Student.prototype.update = function({data,callbackFun} = {}){}
/**
* 删除学生信息
* @param {string[]} ids - 学生ID
* @param {object} params
* @param {function} [params.callbackFn=null]
*/
Student.prototype.delete = function(ids,params){}
/**
* 获取学生信息
* @param {number} id - 学生ID
* @param {object} params
* @param {function} [params.callbackFn=null]
*/
Student.prototype.get = function(id,params){}
当前文件夹结构
jsdoc js/demo.js
执行命令后，目录下会多出现一个 out 文件夹，里面是生成的 html
点击预览效果大概是这样子的
到这一步，js 生成文档就生成好了。
通过配置文件，可以配置指定哪些文件需要生成，生成的出口等。更多配置解说可查看官方文档。https://jsdoc.zcopy.site/about-configuring-jsdoc.html
{
"plugins": [],
"recurseDepth": 10,
"source": {
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"sourceType": "module",
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc","closure"]
},
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
根据以上配置，修改一下 jsdoc.json 为自己要的：
{
"plugins": ["plugins/markdown"], // 配置文件中让JSDoc开启Markdown 插件支持
// "recurseDepth": 10, // 使用 -r 命令行选项开启了递归支持, JSDoc的递归深度为10 (recurseDepth).
"source": {
"include": ["js"], // 指定生成文档的文件夹名称，如果没有，需创建
"includePattern": ".js$", // 名为 js 的源文件夹下的所有js都会自动生成文档
"excludePattern": "(node_modules/|docs)" // 忽略文件夹
},
"sourceType": "module",
"templates": {
"cleverLinks": false,
"monospaceLinks": false
},
"opts": {
"recurse": true,
"destination": "./docs/" // 将生成的文放到指定目录下,如不指定，默认输出到 out 文件夹下
}
}
jsdoc -c jsdoc.json
docs文件夹里就是生成的 html 文件了
当预览 index.html 文件时，会发现页面是没有什么内容
这是可以配置 markerdown 来对文档进行说明等
# 使用jdDoc来生成文档
## Hello World示例
这里是根页面
jsdoc -c jsdoc.json README.md
js doc 生成的文档如果使用默认模板样式不仅不美观而且阅读体验感不好，官方也给出了一些模板：
这里拿 docdash 模板来配置
npm install docdash --save-dev
{
"opts": {
"template": "node_modules/docdash"
}
}
预览效果如下：
找模板的时候，还发现了这个 docdash 主题的折叠版 clean-jsdoc-theme 模板。
这个模板有两种主题，一种是 黑色 dark，一种是灰色 light 更多的配置可以去文档查看
clean-jsdoc-theme文档：https://github.com/pencil-js/clean-jsdoc-theme
npm install clean-jsdoc-theme --save-dev
{
"opts": {
"theme_opts": {
"default_theme": "dark" // or "light" // 修改主题，默认是 dark
},
"template": "node_modules/clean-jsdoc-theme"
}
}
预览效果如下：
dark主题
light 主题
自定义模板就是以上的几个模板都不符合要求的话，就需要自定义，设置样式和排版布局等。本人项目中就是使用自定义的，基于 clean-jsdoc-theme 这个模板的代码来进行修改样式和一些侧边栏数据等。
最后附上，完整的 jsdoc.json 文件
