JS源文件的文档注释与提取

开发文档是很有价值的，然而制作和更新文档却不是轻松活。

在JAVA中，有javadoc工具，可以一键提取注释并生成文档。在其它语言中，就不一定这么方便了。

这里介绍一个工具，jsdoc, 可以提取javascript文件里面的注释并生成美观的html文档。

jsdoc识别类似于JAVA的注释标签，如@author、@param、@method等。例如：

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

通过配置文件，可以提供更多选项：

{
    "tags": {
        "allowUnknownTags": true
    },
    "source": {
        "includePattern": ".+\\.js(doc)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

可以看到，它支持目录递归操作。

通过指定自定义的模板，可以按需生成文档。更多的配置可查看这里以及命令行参数

安装jsdoc：

• 安装Nodejs
• 命令行下安装jsdoc包：npm install -g jsdoc

更多：生成markdown文档

事实上，我们也可以直接生成markdown文档。这里需要安装另一个工具包：jsdox

用法如下:

    jsdox [options] <file | directory>
    jsdox --All --output docs folder/file

Options:
  -c, --config  <file>   指定配置文件
  -A, --All              提取所有的可识别的标记，包括私有元素
  -d, --debug            输出调试信息到控制台
  -H, --help             查看帮助
  -v, --version          查看版本信息
  -o, --output           指定输出目录
  -t, --templateDir      指定模板目录

同样的，jsdox可以提取单个文件的注释，也可按目录提取。