JavaScript Documentation

Kazuhito Hokamura

2012.08.15

社内勉強会

ドキュメントを書こう！

どうやって書こう？

メジャーなツール

  • JsDoc Toolkit
  • YUIDoc
  • ext-doc
  • Dox
  • docco

YUIDocいいよYUIDoc

インストールと実行

$ npm install -g yuidocjs
$ yuidoc -o path/to/out path/to/js

これでpath/to/outにドキュメントが生成される

書き方

コード内のコメントに決まった書式で記述する

/**
* Userを管理するクラス
*
* @class User
* @constructor
*/
function User() {
}

メソッドのドキュメント

/**
* 名前のデータを文字列で返す
* 
* @method getName
* @return {String} 名前の文字列
*/
User.prototype.getName = function () {
};

クラスメソッドの宣言

/**
* 条件からユーザーを探す
*
* @method find
* @static
* @return {Array} 条件にマッチしたユーザーのリスト
*/
User.find = function(cond) {
};

パラメーターの指定

/**
* 条件からユーザーを探す
*
* @method find
* @static
* @param cond {Object} 検索条件
* @return {Array} 条件にマッチしたユーザーのリスト
*/
User.find = function(cond) {
};

パラメーターのネスト

/**
* 条件からユーザーを探す
*
* @method find
* @param cond {Object} 検索条件
* @param cond.name {String} 名前から探す場合に指定する
* @param cond.email {String} メールアドレスから探す場合に指定する
* @param cond.age {Number} 年齢から探す場合に指定する
* @return {Array} 条件にマッチしたユーザーのリスト
*/
User.find = function(cond) {
};

オプショナルなパラメーター

/**
* 条件からユーザーを探す
* @method find
* @param cond {Object}
* @param cond.name {String} 名前から探す場合に指定する
* @param cond.email {String} メールアドレスから探す場合に指定する
* @param cond.age {Number} 年齢から探す場合に指定する
* @param [option] {Object} オプション
* @param [option.limit] {Number} 結果件数の上限数
* @return {Array} 条件にマッチしたユーザーのリスト
*/
User.find = function(cond, option) {
};

markdownとしてパースされる

/**
* 条件からユーザーを探す
*
* ### 名前から探す場合
*
*     var users = User.find({
*       name: 'hokamura'
*     });
*
* ### 名前と年齢から探す場合
*
* 条件を二つ指定するとand検索になる
*
*     var users = User.find({
*       name: 'hokamura',
*       age: 20
*     });
*
* ### limitの指定
*
* オプションでlimitを指定することで結果の件数の上限を指定する
*
*     var users = User.find({
*       name: 'hokamura'
*     }, {
*       limit: 10
*     });
* 
* @method find
* @static
* @param cond {Object} 検索条件
* @param cond.name {String} 名前から探す場合に指定する
* @param cond.email {String} メールアドレスから探す場合に指定する
* @param cond.age {Number} 年齢から探す場合に指定する
* @param [option] {Object} オプション
* @param [option.limit] {Number} 結果件数の上限数
* @return {Array} 条件にマッチしたユーザーのリスト
**/
User.find = function(cond, option) {
};

イベントのドキュメント

/**
* データを設定したとき発火するイベント
*
* @event change
* @param user {user} 変更されたユーザーモデル
*/

CoffeeScriptでも
ドキュメントを生成したい

YUIDoc version 0.3.19+

###*
# This is the description for foo class.
#
# @class User
# @constructor
###

class User

$ yuidoc -e .coffee --syntaxtype coffee path/to/coffee

まとめ

  • ドキュメント書こう！
  • YUIDocいいよYUIDoc
  • もっと色々指定できるから詳しくはドキュメントみてね！

Thanks.