JSDoc

2016-03-26 本文已影响6482人 6ed7563919d4

随着ES2015的定稿，模块化已经成为前端开发的规范被执行，清晰的模块化使得开发者与开发者之间的依赖便的更小，当项目还小时，可以通过查找一下模块源文件中的声明就能大致了解模块的功用。然而，随着项目的不断增长以及各项目之间的整合，开发者对其他模块的内容知之甚少，如果来源于不同项目，只是项目间的依赖的话，那么源代码有可能也无法在当前开发环境下找到，此时，开发者都会想到有个API文档那该多好啊。

所以，前端代码文档化势在必行。

前端代码主要以js为主，主流的文档生成器便是JSDoc，最近项目是使用的ES2105编写的，JSDoc3.4.0之后已经提供了对ES2015的支持。

安装JSDoc

npm i jsdoc -g

如何使用JSDoc

同其他语言一样，文档生成工具的原理还是通过代码注释去解析并根据一定的tag来生成文档。在JSDoc文档中明确说明了，只有以/**为开始的注释才会被JSDoc识别，其他的注释格式都会被忽略。

额外，JSDoc 默认还会将项目中的README.md文件一同生成到JSDoc最后生成的文档文件中，或通过命令--R/-readme 指定个别文件，将其添加至所生成的文档文件中，但文件格式必须是Markdown，此时，项目中的README.md将被忽略。

JSDoc命令行参数

JSDoc命令行几个常用参数有以下几个：

-c, --configure 指定configuration file
-d, --destination 指定输出路径，默认./out
-e, --encoding 设定encoding，默认utf8
-p, --private 将private注释输出到文档，默认不输出
-P, --package 指定package.json file
-r, --recurse 查询子目录
-t, --template 指定输出文档template
-u, --tutorials 指定教程路径，默认无

JSDoc配置文件

同许多js工具一样，JSDoc也有配置文件，可以通过设定配置文件来定制JSDoc。如果没有指定configuration file，将会使用一下配置。

{
    "tags": {
        "allowUnknownTags": true, // 允许使用自定义tag
        "dictionaries": ["jsdoc","closure"] // 定义tag集
    },
    "source": {
        "includePattern": ".+\\.js(doc)?$", // 将以.js, .jsdoc结尾的文件作为源文件
        "excludePattern": "(^|\\/|\\\\)_" // 忽略以_开头的文件夹及文件
    },
    "plugins": [],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

以上这个是默认配置，下面解释几个常用配置。

source：顾名思义是用来指定源文件的，在其之下包含了4个属性，其中两个已经在默认配置中出现过了。
|- include: [ array of paths to files to generate documentation for ], // 源文件路径数组
|- exclude: [ array of paths to exclude ], // 排除文件路径数组
|- includePattern: a regular expression, // 接受一个正则表达式，当文件名匹配这个正则时，执行JSDoc
|- excludePattern: a regular expression, // 接受一个正则表达式，当文件名匹配这个正则时，JSDoc忽略该文件
JSDoc以以下的顺序执行这些属性：
1. 根据include获取目标文件
2. 根据includePattern筛选由第一步得到的目标文件
3. 根据excludePattern筛选由第二步得到的文件
4. 最后根据exclude属性，排除由第三步得到的文件结果集，排除之后的文件便是JSDoc需要执行的源文件。
tags: 用来指定tag库，tags下面有2个属性，分别是
|- allowUnknownTags: 用来告诉JSDoc如何处理标签库以外的tag，设为false时，JSDoc不会处理标签库以外的tag，但会记录一个警告，默认为true
|- dictionaries: 数组格式，指定标签库，标签库越靠前，优先度越高
opts: 命定行参数可以在此属性下配置，列如：

  "opts": {
    "template": "templates/default",  // same as -t templates/default
    "encoding": "utf8",               // same as -e utf8
    "destination": "./out/",          // same as -d ./out/
    "recurse": true,                  // same as -r
    "tutorials": "path/to/tutorials", // same as -u path/to/tutorials
}

plugins: 配置额外的插件，如markdown插件，与此同时，JSDoc也可以编写自定义插件做额外的处理。
templates: 可以用来配置默认template的格式，或另外指定自定义的template

Namepaths

namepath在JSDoc中起着至关重要的作用，JSDoc namepath会提供一个唯一的标识给任意一个变量，这使得你在使用inline tag时，可以方便的找到任何一个变量，从而提供一个指向该变量的链接。

MyConstructor                // 父元素
MyConstructor#instanceMember // 成员变量使用#
MyConstructor.staticMember   // 静态变量使用.
MyConstructor~innerMember    // 内部成员使用~
                             // module使用:

JSDoc

安装JSDoc

如何使用JSDoc

JSDoc命令行参数

JSDoc配置文件

Tags

Namepaths

猜你喜欢

热点阅读