イヌ型ドキュメントで開発効率アップ!? JSDogを使ってみよう。

JavaScriptのドキュメント生成ツールと言えば、JSDoc Toolkitが有名です。

でも何か、物　足　り　な　い。

そこでJSDogです。

JSDogは、JSDocの書き方で「犬」のドキュメントが生成されます。

インストールはnpmで。

$ sudo npm install -g jsdog

書き方はこんな感じです。

/** ++*[npmtools.js]*++ - npmのpackage.jsonを読み込むプログラム
 * 
 * @version 0.0.1
 * @author Tomoyuki Inoue
 */

var fs = require('fs');

/**
 * 指定したパスからpackage.jsonファイルを探索します。
 * @method readPackageJson
 * @param {string} path 読み込みを開始するパスを指定します。
 * @param {function} cb 読み込み完了かエラー時のコールバックを指定します。
 */
var readPackageJson = function(path, cb){
    // パスの読み込み開始
    var path = path + "/node_modules";
    fs.readdir(path, function(err, dirs){
        if(err) cb(err, null);
        // dirsには指定したパスのファイル名・ディレクトリ名の一覧が入っている
        for(var i = 0; i < dirs.length; i++){

            var dir = dirs[i];
            // 頭文字が.の場合読み込まない
            if(dir.charAt(0) === '.') continue;
    
            // package.jsonのパスを指定
            var jsonPath = path + "/" + dir + "/package.json";
    
            // package.jsonを読み込み開始
            fs.readFile(jsonPath, function(err, data){
                if(err) cb(err, null);
                // dataには読み込んだBufferが入っている
                // toString('utf8')で文字列にする
                var jsonStr = data.toString('utf8');
                // JSONをパースしてコールバック
                cb(null, JSON.parse(jsonStr));
            }); 
        }   
    }); 
};

readPackageJson(".", function(err, json){
    if(err) throw err;
    console.log(json.name +"@" + json.version );
});

使い方はコマンドラインで。

$ jsdog -s npmtools.js > index.html

見事に文字化けします。

テンプレートの最初の数行を修正します。

テンプレートはJadeで書かれています。ファイルは、/usr/local/lib/node_modules/jsdog/default.jade あたりにあると思います。

修正前

!!! 5
html(lang="en")
  head
    title= pageTitle

修正後（lang属性削除、メタcharset追加）

!!! 5
html
  head
    meta(charset="utf-8")
    title= pageTitle

もう一度実行すると文字化けが解消。

まだまだ不安定ですが面白いですね。

テンプレートもJade形式なので簡単です。ちょっと修正すると・・・

な事もできます。