SYSTEM238 / NOTES1 / PHP / PHPDocの書き方のまとめ

NOTES1 PROG1
PHPDocの書き方のまとめ
自分流のPHPDocの書き方をまとめたノート。

PHPDocとは

PHPDocとはJavadocのPHP版です。

クラス、メソッドのソースコメントをルールに従って記述するとHTML形式のAPI仕様書を自動生成することができます。また、PhpStormなどのIDEではPHPDoc形式のコメントを元にコード補完やエラーチェックを行います。

ちなみに現在はPHPDocではなくPHPDocumentorとしてPEARパッケージで提供されています。

PHPDocの詳細についてはhttp://www.phpdoc.org/docs/latest/を参照してください。

よく使うダグ

よく使うタグです。これ以外のタグは(私は)あまり使いませんすいません。

@author

@author [name] [<email address>]

/**
 * ex.
 * @author taro <taro@urasima.jp>
 */

@authorタグは作成者を示すタグです。

作成の比率や担当部分によってクラスのコメントで記述したり、メソッドのコメントで記述したりしてます。

@param

@param [Type] [name] [description]

/**
 * ex.
 * @param string      パラメタ1 
 * @param string[]    パラメタ2   配列は型をarrayとするより[]で記述する方が良い
 * @param string|null パラメタ3   パラメタが複数の型になる場合
 */

@paramタグはメソッドのパラメタを示すタグです。

PhpStormなんかはこのタグを元にコード補完やエラーチェックをします。最重要のタグです。他のタグはサボっても@paramと@returnタグだけは忘れずに!!

@return

@return [Type] [description]

/**
 * ex.
 * @return array  検索成功はレコードの配列が、失敗はarray()が戻る
 */

@returnタグはメソッドの戻り値を示すタグです。

PhpStormなんかはこのタグを元にコード補完やエラーチェックをします。最重要のタグです。他のタグはサボっても@paramと@returnタグだけは忘れずに!!

@see

@see [URI | FQSEN] [description]

/**
 * ex.
 * @see http://.../.../      チェックデジットは7DR方式
 * @see MyClass::$items      最大値は$itemsを変更する
 * @see MyClass::setItems()  合わせて修正すること
 */

@returnタグは関連する情報を示すタグです。

仕様に外部(法令とか)が影響する場合の参照先や、一緒に修正しなければいけないメソッドがある場合などの参照先を記述してます。

@throws

@throws [Type] [description]

/**
 * ex.
 * @throws ViolatesForeignKeyConstraint レコード削除時に参照整合性制約に違反した場合に発生します
 */

@throwsタグはそのメソッドが発行する例外オブジェクトを示すタグです。

例外を発行するメソッドには書くようにします。try ~ catchを作成する時の参考になります。

@todo

@todo [description]

/**
 * ex.
 * @todo 2037年以降の動作は保証していません。
 */

@todoタグはAPI仕様書に表記するtodoを示すタグです。

開発途中のtodoなどは開発ルールで決めた書き方やIDEのtodoなどで記述します。@todoはAPI仕様書などのドキュメントに記載するべきtodoを記述します。

@var

@var [Type] [$element_name] [description]

/**
  * @var string $name        プロパティの説明
  * @var string $description プロパティの説明
  */
protected $name, $description;

@varタグはオブジェクトのプロパティを示すタグです。

プロパティをどのように使用するか記述しておきます。

似たようなタグに@property[-read|-write]がありますが、こっちはマジックメソッド(__get(), __set())を使ってプロパティやメソッドを動的に作成する場合にします。

@propertyの詳細はPHP: オーバーロード - ManualphpDocumentor:@propertyを参照してください。

@version

@version [vector] [description]

/**
 * @version 1.0.1
 */

/**
 * @version $Id$
 */

@varタグはバージョンを示すタグです。

Subversionやgitなどのバージョン管理システムで自動設定できる環境が整ってれば使用します。手動では正直なところ管理しきれないので使用しません。

@paramと@returnのType

PHPの型

  • null
  • string
  • integer (int)
  • boolean (bool)
  • float (double)
  • object
  • array
  • resource

その他

  • void
  • callback
  • mixed
  • true
  • false
  • self
  • クラス名

複数の型を指定する

integer|float|null のように"|"で区切って列挙すると複数の型を指定できる。

配列

  • array
  • PHPの型[ ] ... 例) string[ ]

記述例

<?php
/**
 * クラス名
 * 
 * クラスの説明
 * API仕様書で概要説明になるのを意識して書く。細かい説明は各メソッドへ。
 * 
 * @author tarou <tarou@momo.jp>
 * @version $Id$
 */
class parent
{
    /**
     * @var string $NAME  ユーザ名
     */
    private   $NAME;

    /**
     * @var object $INI   設定
     * @var object $TPL   Smartyテンプレート
     */
    protected $INI, $TPL;

    /**
     * メソッド名
     *
     *メソッドの説明
     * API仕様書の説明になるのを意識して書く。
     * が、たくさん書くと修正が発生した時が面倒なんで、ソースを読むことを前提に概要や注意点
     * だけでもいいんじゃないかと個人的には思ってる。
     *
     * @param  int[] $valAry  集計する値
     * @return int            答え
     */
    static function plus($valAry)
    {
        $sum = 0;
        foreach ($valAry as $val) $sum += $val;
        return $sum;
    }
}