YUIDocを使ってみたよ

JavaScript向けのドキュメントジェネレータというと、JSDoc toolkitとかDoccoなどがありますが、YUIDocが程よく手軽な感じで使ったこともなかったので使ってみました。
昔はJavaかなんかで作られてた気がするのですけど、いまではnpmモジュールになってるのですね。node.js + npmが入ってるならとってもインストールはとっても簡単。

インストール

npmからインストールします。

$ npm install -g yuidocjs

でインストールするとよいかと。今回はグローバルにインストールしたくなかったので

$ npm install yuidocjs

でインストールして

$ ./node_modules/.bin/yuidoc

で使うことにします。

適当なコードを書く

適当なJavaScriptのコードを書きます。

index.js
/**
 * Classクラスです。
 *
 * @class Class
 * @constructor
 */
function Class() {
}

/**
 * hogeメソッドです。
 *
 * @method hoge
 */
Class.prototype.hoge = function () {
  
  /**
   * aaa
   *
   * @private
   * @method aaa
   * @param a {String} a
   * @param b {String} b
   * @param c {String} c
   * @return Object
   */
  var aaa = function (a, b, c) {
    return {
      a: a,
      b: b,
      c: c
    };
  };
};

いい加減すぎるコードですが、まあ……

生成する

生成します。

$ ./node_modules/.bin/yuidoc -x node_modules/ .

-xは除外するファイル・ディレクトリで、最後のドットはjsファイルを検索する場所です。
カレントディレクトリにindex.jsが置いてあるだけですが。
デフォルトだとサブディレクトリも再帰的に検索して生成してくれるようです。


生成するとoutというディレクトリが生成されて、index.htmlなどのファイルが置いてあります。

見た目

index.htmlを開いてClassクラスのメソッドを見たところのスクリーンショットです。

デフォルトのテンプレートでもすっきりした感じのデザインで良い感じ。


全然関係ないけど、gjslintでドックコメントの最後にピリオドつけろっていう警告、句点に変えられないのかな……


とまあ、YUIDocでドキュメントを生成してみたのでした。
JavaDoc形式でかっちり書くのも良いのですが、Docco的にMarkdownで気楽に書くのも楽でよいなあと思っているので、どうしようかなあと。
ライブラリはかっちりJSDoc ToolkitかYUIDocで、ライブラリを使う部分はDoccoとかで書いたら良いのかなーと思ったり。逆に面倒か。