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能夠提取單個文件的註釋，也可按目錄提取。