検索してもあまり日本語の情報が出てこなかったのでメモを残しておきます。

JSDoc #

JSDoc は言うまでもないですが、JavaScript のソースコード に残したコメントから自動的にリファレンスドキュメントを生成してくれるコマンドライ ンツール。例えばこんな感じでソースにコメントを書いておくと

/**
* Resolve url from `srcset` syntax http://www.w3.org/html/wg/drafts/srcset/w3c-srcset/
* @param {string} src Default URL
* @param {string} srcset `srcset` argument
* @param {number|undefined} dpr Device pixel ratio
* @param {number|undefined} width Viewport width
* @return {string} Parsed and resolved URL
* @private
*/

var resolveSrcset = function(src, srcset, dpr, width) {
if (srcset === null) return src;
...
};

下記のような HTML を出力してくれます。

便利ですね。

Grunt #

詳しくは公式ドキュメントを参考 にして頂ければと思いますが、今時は Grunt を使って、これを 自分のワークフローに手軽に組み込むことができます。例えば僕は Grunt でこんなこと をしています。

ここに「JSDoc でリファレンスドキュメントを生成する (grunt-jsdoc)」も追加することがで きます。

この grunt-jsdoc ですが、見ての通 り、そのまま出力してしまうと、かなりプレーンで寂しい感じになってしまうわけです が、ひと工夫加えると、下記のように素敵なデザインにすることができます。

docstrap #

実は grunt-jsdoc には docstrap という ものが dependency として含まれているのですが、これを使うことで、見た目を簡単に  bootstrap を使ったコジャレたものにすることができる のです。デザインは bootswatch.com で提供されているもの から選べます。

で、その使い方なのですが、ドキュメントも分かりづらいし検索してもあまり情報がな かったのでここに残しておきます。

まずは Gruntfile.js の記述ですが

jsdoc: {
dist: {
src: ['src/*.js', 'README.md'], // JSDoc化したいソースコードへのパス
options: {
destination: 'doc', // 出力先パス
configure: 'jsdoc-config.json' // docstrapの設定ファイル
}
}
}
...
grunt.loadNpmTasks('grunt-jsdoc');

こんな感じにします (Grunt の作法が分からない方は、まずはその辺りを先に修得する必 要があります) 。ポイントは configure: 'jsdoc-config.json' の部分で、別のファイ ルに詳細を記述する必要があります。これは grunt-jsdoc の設定自体は Gruntfile.js に記述できるのですが、docstrap の設定 は別ファイルにせざるを得ないためです。

ここでは、jsdoc-config.json というファイルを指定しているので、そういう名前のファ イルを作りましょう。中身はこんな感じ。

{
"plugins": [
"plugins/markdown" // Markdownプラグインを入れるとコメントがMarkdownで書けます!
],
"templates" : {
"cleverLinks" : false,
"monospaceLinks" : false,
"default" : {
"outputSourceFiles" : true
},
"systemName" : "PortableCache",
"footer" : "",
"copyright" : "Developed by Eiji Kitamura",
"navType" : "vertical",
"theme" : "united", // bootswatch.comのデザイン名を小文字で指定
"linenums" : true,
"collapseSymbols" : false,
"inverseNav" : true
},
"markdown" : {
"parser" : "gfm",
"hardwrap" : true
},
"opts": {
// ここがポイント
"template": "node_modules/grunt-jsdoc/node_modules/ink-docstrap/template"
}
}

ポイントは opts.template の部分で、これをそのまま記述する必要があります。そし て、templates.theme に bootswatch.com で気に入ったデ ザインの名前を小文字で入力。後はタスクを走らせれば OK。のはず。

おまけ #

実は JSDoc は README.md などの markdown で書かれたファイルをトップページに組み込 むことができます。使い方は、上記の通り変換するソースの一覧に加えるだけ。
また、これも JSDoc 自体が持つ機能ですが、プラグインで markdown を入れておくとコ メントにも markdown 記法が使えて大変便利です。