phpDocumentorの書き方

phpDocumentorの書き方ってこれ！っていうベストプラクティスがなくて（ドキュメントとはそういうものなのかもしれないけど…）、毎回試行錯誤して、フォーマットを考えるだけでも時間を取られるので、一度自分なりのフォーマットをまとめたいと思います。

今回は、クラスとメソッドについてまとめています。
プロパティについても書いたほうがドキュメントとしてはよいと思うのですが、プロパティまで書き出すとなかなか継続出来ない（ダメ人間です）ので、追々。。

ちなみに、CakePHPをやんわり想定しています。

では、まずクラスについて。

クラス：フォーマット

/**
 * [区分]クラスの概要
 *
 * クラスの詳細
 * 出来るだけ細かく書いたほうがよいが、詳細な説明は各メソッドに任せる。
 * 全体での共通ルールとか仕様を書く。
 *
 * @access アクセスレベル
 * @author 名前 <メールアドレス>
 * @copyright 会社名 All Rights Reserved
 * @category カテゴリー（処理系）
 * @package パッケージ（MVC）
 */

説明

区分には、[API]とか[CMS]とかそういった情報を書く。
カテゴリーは、基本的には処理単位というかコントローラーとモデルがセットになるようにする。
ただし、CakePHPの場合、モデルクラスがアクティブレコードを持つように（僕は）設計することが多いので、アクティブレコードのクラスは"ActiveRecord"とする。
あと、あんまりないですが、個別にバリデーションクラスを用意しているときは、"Validation"とする。
パッケージは、コントローラーだったらContoroller、モデルだったらModelと書く。

具体的にはこんな感じ。

クラス：具体例

/**
 * [API]メッセージ送信系APIコントローラークラス
 *
 * メッセージ送信に関するAPIをまとめたコントローラークラス。
 * エンドポイント単位でメソッドを定義する。
 *
 * @access public
 * @author itosho <hogehoge@example.com>
 * @copyright  hogehoge Corporation All Rights Reserved
 * @category Message
 * @package Controller
 */

では、次にメソッド。

メソッド：フォーマット

/**
 *  [区分]関数の概要
 *
 *  関数の詳細
 *  出来るかぎり細かく書く！でもシンプルに！（難しい）
 *
 * @access アクセスレベル
 * @param 型 パラメーター名（物理名） パラメーター型名（論理名）
 * @return 型 戻り値（物理名） 戻り値（論理名）
 * @see 関連（呼び出したり）する関数
 * @throws 例外についての記述
 * @todo 未対応（改善）事項等
 */

説明

区分は、クラスと同じような感じか、リクエストメソッドで分けているときは、[POST]とか[GET]とか書く。
が、メソッドの場合は、書かなくてもよいこととする。
パラメーター（引数）と戻り値は必ず型も書いて、物理名だけじゃなく論理名も書く。
see、throws、todoは必要と（やる気）に応じて書く。

メソッドはコントローラーとモデルでタグが違うことが多いので、それぞれ具体例を書きます。

メソッド：具体例（コントローラー）


/**
 * [POST]メッセージ送信APIのコントローラー関数
 *
 * 即時送信の場合は、実際にメッセージ送信処理を行う。
 * 予約送信の場合は、メッセージの登録処理のみを行う。
 *
 * @access public
 * @see MessageApi::paramCheck
 * @throws NotFoundException メッセージがない場合は404エラーを返す
 */

メソッド：具体例（モデル）


/**
 * メッセージ登録処理用の関数
 *
 * メッセージ登録後、送信者情報も更新する。
 * 送信者情報の更新はREPLACE INTOで更新する。
 *
 * @access public
 * @param array $sender
 *          送信者情報
 * @param array $params
 *          リクエストパラメーター
 * @return integer $messageId メッセージID（エラー時は0）
 * @todo パフォーマンス改善の余地あり
 */

※念のためですが、上記の具体例は実際のドキュメントを改変しています。
（ので、細かいところで変な点はあるかと思いますが、それが主旨ではないので、大目に見ていただければと思います。）

まとめ

基本的には、詳細に書いたほうがよいので、上記のフォーマットを一例にしつつ、例えば、どんどんタグも増やしていただいて構いませんが、やり過ぎるとだんだんドキュメントを書くのが億劫になっていくのと、メンテも大変だと思うので、最小公倍数的な感じでよいと考えています。
ただ、絶対避けたいのは同一のプロダクト内で、このメソッドはドキュメントが詳細（≒正確）に書かれているけど、こっちのメソッドはドキュメントが粗いないしは間違っていることだと思うので、やり切れる範囲でやり切るのが大事かと思います。
（もちろんやり切れる範囲を広げていく努力は必要）

あとは、その最小公倍数的な感じ（シンプルだけど必要な情報は詰め込まれている）を上手に書けるように日々精進！

最後に

これはだめだぜ！こうしたほうがよいぜ！うちはこうしてるぜ！とかありましたらコメントなりいただけると嬉しいです。

参考サイト

phpDocumentor：
http://www.phpdoc.org/docs/latest/index.html
（公式のドキュメントです。タグ一覧もここから見れます。）