jsdoc的使用

仅使用与js文件，增加代码可读性

我在百度上搜索好多不知道怎么用，后来终于找到一篇

使用：

# 首先在全局安装（是不是项目依赖全局啊，我也不知道，求解答）
npm install -g jsdoc
#  当前项目安装
npm install --save-dev jsdoc
# 使用方法（cmd 中运行就可以了）
jsdoc XXXX.js

创建之后你可以尝试一下，jsdoc 如果是本地没有相关指令，就是没有安装成功，安装全局试试记得，然后找个js文件

/**
 * Book类，代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book(title, author) {
    this.title=title;
    this.author=author;
}
Book.prototype={
    /**
     * 获取书本的标题
     * @returns {string|*}
     */
    getTitle:function(){
        return this.title;
    },
    /**
     * 设置书本的页数
     * @param pageNum {number} 页数
     */
    setPageNum:function(pageNum){
        this.pageNum=pageNum;
    }
};

命令行编译文件

jsdoc demo.js

大抵是这样子的：

后面这些还没有尝试

默认的话是生成在一个 out 目录下的，当然你也可以使用 -d 命令指定其他的目录

jsdoc -d yourPathName（你的路径） XXXXXX.js

其他的，先复制过来再说

jsdoc提供了大量命令行选项满足使用需求，这里列出一些常用选项：

-c 或 --configure：指定JSDoc配置文件的路径。默认为安装JSDoc目录下的conf.json或conf.json.EXAMPLE
-d 或 --destination：指定输出生成文档的文件夹路径。JSDoc内置的Haruki模板，使用console 将数据转储到控制台。默认为 ./out
-r 或 --recurse：扫描源文件和导览时递归到子目录
-R 或 --readme：用来包含到生成文档的README.md文件。默认为在源路径中找到的第一个README.md文件
-t 或 --template：用于生成输出文档的模板的路径。默认为templates/default，JSDoc内置的默认模板
-v 或 --version：显示jsdoc版本号
更多选项可通过 -h 或 --help选项查看，或通过传送门到官网或中文文档查看
每次都输入一长串命令行太过繁琐，可在配置文件中的opts参数中指定这些选项

用conf.json配置JSDoc

{
    "tags": {
        "allowUnknownTags": true
    },
    "source": {
        "include": ["./src"],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_",
        "exclude": ["./src/index.js"]
    },
    "plugins": [],
    "opts": {
        "template": "./doc/templates/docdash",
        "encoding": "utf8",
        "destination": "./doc/doc-page/",
        "recurse": true
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false,
        "default": {
            "outputSourceFiles": true
        }
    }

其中：

tags：控制那些标签允许被使用和解析
source：指定要用jsdoc生成文档的文件
include：路径组成的数组，jsdoc将为它们生成文档
exclude：路径组成的数组，jsdoc应忽略的路径
includePattern：正则表达式字符串，只有文件名匹配的文件才会被jsdoc扫描。默认为 .+.js(doc)?$ 即 .js 或 .jsdoc 结尾的文件才会被扫描
excludePattern：正则表达式字符串，文件名匹配的文件将被jsdoc忽略。默认为 (^|\/|\\)_ 即下划线开头的文件或下划线开头的目录下的所有文件
结合起来，jsdoc的执行过程是：
扫描include中的所有文件（若使用了 -r 命令将在子目录中递归搜索）
在上一步搜索到的文件中，使用includePattern匹配文件名，只保留相匹配的文件
在上一步匹配到的文件中，使用excludePattern匹配文件名，剔除相匹配的文件
在上一部生于的文件中，如果文件路径在exclude中，该文件将被剔除
最终剩下的文件将通过jsdoc进行解析
opts：配置命令行选项，与上面讲的选项相对应
plugins：要启用的插件，在数组中添加插件相对于JSDoc文件夹的路径即可
templates：配置jsdoc所生成的文档的模板
配置完成后使用 ./node_modules/.bin/jsdoc -c path/to/yourconf.json 生成jsdoc文档即可