JSDocでJavaScriptプロジェクトのドキュメントを作る

関数リファレンス的なのを作りたい時もありつつ、自力でつくるのは面倒だなと思ったので、ようやく触ってみました。

インストール

$ npm i -g jsdoc
$ jsdoc -v
JSDoc 3.5.5 (Thu, 14 Sep 2017 02:51:54 GMT)
$ jsdoc -h
JSDoc 3.5.5 (Thu, 14 Sep 2017 02:51:54 GMT)

Options:
    -a, --access <value>         Only display symbols with the given access: "package", public",
                                 "protected", "private" or "undefined", or "all" for all access
                                 levels. Default: all except "private"
    -c, --configure <value>      The path to the configuration file. Default:
                                 path/to/jsdoc/conf.json
    -d, --destination <value>    The path to the output folder. Default: ./out/
    --debug                      Log information for debugging JSDoc.
    -e, --encoding <value>       Assume this encoding when reading all source files. Default: utf8
    -h, --help                   Print this message and quit.
    --match <value>              When running tests, only use specs whose names contain <value>.
    --nocolor                    When running tests, do not use color in console output.
    -p, --private                Display symbols marked with the @private tag. Equivalent to
                                 "--access all". Default: false
    -P, --package <value>        The path to the project's package file. Default:
                                 path/to/sourcefiles/package.json
    --pedantic                   Treat errors as fatal errors, and treat warnings as errors.
                                 Default: false
    -q, --query <value>          A query string to parse and store in jsdoc.env.opts.query.
                                 Example: foo=bar&baz=true
    -r, --recurse                Recurse into subdirectories when scanning for source files and
                                 tutorials.
    -R, --readme <value>         The path to the project's README file. Default:
                                 path/to/sourcefiles/README.md
    -t, --template <value>       The path to the template to use. Default:
                                 path/to/jsdoc/templates/default
    -T, --test                   Run all tests and quit.
    -u, --tutorials <value>      Directory in which JSDoc should search for tutorials.
    -v, --version                Display the version number and quit.
    --verbose                    Log detailed information to the console as JSDoc runs.
    -X, --explain                Dump all found doclet internals to console and quit.

Visit https://usejsdoc.org for more information.

サンプルコード

とりあえず適当なコードを入れておきましょう。

module.exports.hasValidToken = token => {
  if (!token) return false
  if (/^wp/.test(token)) return true
  return false
}

JSDocを走らせると、out/ディレクトリ配下にhtmlが出力されます。

$ jsdoc FILE_NAME.js 
$ tree
.
├── index.js
├── modules.js
├── out
│   ├── fonts
│   │   ├── OpenSans-Bold-webfont.eot
│   │   ├── OpenSans-Bold-webfont.svg
│   │   ├── OpenSans-Bold-webfont.woff
│   │   ├── OpenSans-BoldItalic-webfont.eot
│   │   ├── OpenSans-BoldItalic-webfont.svg
│   │   ├── OpenSans-BoldItalic-webfont.woff
│   │   ├── OpenSans-Italic-webfont.eot
│   │   ├── OpenSans-Italic-webfont.svg
│   │   ├── OpenSans-Italic-webfont.woff
│   │   ├── OpenSans-Light-webfont.eot
│   │   ├── OpenSans-Light-webfont.svg
│   │   ├── OpenSans-Light-webfont.woff
│   │   ├── OpenSans-LightItalic-webfont.eot
│   │   ├── OpenSans-LightItalic-webfont.svg
│   │   ├── OpenSans-LightItalic-webfont.woff
│   │   ├── OpenSans-Regular-webfont.eot
│   │   ├── OpenSans-Regular-webfont.svg
│   │   └── OpenSans-Regular-webfont.woff
│   ├── index.html
│   ├── scripts
│   │   ├── linenumber.js
│   │   └── prettify
│   │       ├── Apache-License-2.0.txt
│   │       ├── lang-css.js
│   │       └── prettify.js
│   └── styles
│       ├── jsdoc-default.css
│       ├── prettify-jsdoc.css
│       └── prettify-tomorrow.css
└── package.json

とはいえ、なにもドキュメントを書いていない状態なのでまだ何もでてきません。

JSDocを書く

とりあえずざっと書いてみました

/**
 * tokenがwpから始まる正しい形式か確認する
 *
 * @param {string} token - api token
 * @return {bool} check result
 * @since 0.0.1
 * @todo need unit test
 * @example
 * // return true
 * hasValidToken('wpXXXXX')
 * // return false
 * hasValidToken('xxxx')
 **/
module.exports.hasValidToken = token => {
  if (!token) return false
  if (/^wp/.test(token)) return true
  return false
}

@param: 引数の説明
@return: 戻り値の説明
@since: この関数がどのバージョンからあるか
@todo: やる予定のこと
@example: どう使うかのサンプル

のような認識でいいかなと思います。

この状態でjsdocを実行すると、以下のような表示になります。

使い所など

-d docs/オプションをつけると、GitHub PagesとしてJSDocsの中身を公開できます。npm i -D jsdocにして、CIの中でドキュメント生成するような形にすると、効率化できてよいかもしれません。

とりあえずask-utilsのドキュメントを作り始めてみたので、何かあればPRくださいませ。