以下の表記の意味は次のとおりです。
ファイルについて説明を、各ファイルの先頭( "<?php" の次の行、つまり2行目)から書きます。
全てのController、Model、ViewのPHPコードを含むファイルに、この記述が含まれていなければなりません。
<?php /** * このファイルの短い説明 * * このファイルの長い説明 # 必須ではありません。 * * LICENSE: ライセンスに関する情報 * * @category Setuco * @package モジュール名 * @subpackage サブディレクトリ名 * @license http://www.opensource.org/licenses/gpl-2.0.php GNU General Public License, version 2 * @copyright Copyright (c) 2010 SetucoCMS Project.(http://sourceforge.jp/projects/setucocms) * @link * @version * @since File available since Release 0.1.0 * @author GitHubアカウント名 */
ViewのPHPコードには、Viewにどの変数が渡されるのかを "@param" のアノテーションを記入してください。
* @param 型 変数名 変数の説明
クラスについての説明を、クラスを定義する直前に書きます。
ファイルについてのコメントと同じアノテーションは、同じ値にしてください。
edit/**
* このクラスの説明
*
* @package モジュール名
* @subpackage サブディレクトリ名
* @author GitHubアカウント名
*/
class クラス名
{
}
クラス定数の直前には、その定数の説明を書きます。
次に挙げる、フィールド変数やクラス変数との違いに注意してください。
/** * 説明用のクラス定数 */ const CONST_HOGE = 'hoge';
変数の説明と "@var" のアノテーションで、変数の型を書きます。
変数の型が動的に変化する場合は、型を "mixed" にします。
/** * 変数の説明 * * @var 型 */ protected $hoge;
アクションメソッドは、引数と戻り値がありませんので、"@return void"と"@author" のアノテーションをつけます。
クラスの作成者とメソッドを新しく作成する人が同じ人とは必ずしも一致しない可能性がありますので、メソッドを作成する毎にメソッドのドキュメントブロックの "@author" を書いてください。
/**
* アクションの説明
*
* @return void
* @author GitHubアカウント名
*/
public function hogeAction()
{
}
アクションメソッドと違い引数や戻り値がありますので、引数の数だけ"@param"をつけ、必ず一つの"@return"をつけます。
もし戻り値がないメソッドの場合は、"@return"は"@return void"と書きます。
/**
* メソッドの説明
*
* @param 型 $hoge 説明
* @param 型 $foo 説明
* @param 型 $bar 説明
* @return ＜型 説明 | void＞
* @author GitHubアカウント名
*/
public function メソッド名($hoge, $foo, $bar)
{
}
Admin_MediaControllerの場合
(ファイルの場所はapplication/modules/admin/controllers/MediaController.php)
/** * ファイル管理のコントローラ * * LICENSE: ライセンスに関する情報 * * @category Setuco * @package Admin * @subpackage Controller * @license http://www.opensource.org/licenses/gpl-2.0.php GNU General Public License, version 2 * @copyright Copyright (c) 2010 SetucoCMS Project.(http://sourceforge.jp/projects/setucocms) * @link * @version * @since File available since Release 0.1.0 * @author akitsukada */ /** * ファイル管理画面の操作を行うコントローラ * * @package Admin * @subpackage Controller * @author akitsukada */
Admin_model_Mediaの場合
(ファイルの場所 application/modules/admin/models/Media.php)
/** * 管理側のファイル管理用サービス * * LICENSE: ライセンスに関する情報 * * @category Setuco * @package Admin * @subpackage Model * @license http://www.opensource.org/licenses/gpl-2.0.php GNU General Public License, version 2 * @copyright Copyright (c) 2010 SetucoCMS Project.(http://sourceforge.jp/projects/setucocms) * @link * @version * @since File available since Release 0.1.0 * @author akitsukada */ /** * ファイル管理クラス * * @package Admin * @subpackage Model * @author akitsukada */
Common_Model_DbTable_Tagの場合
(ファイルの場所 application/modules/common/models/DbTable/Tag.php)
/** * tagテーブルのDbTable(DAO)クラスです。 * * LICENSE: ライセンスに関する情報 * * @category Setuco * @package Common * @subpackage Model_DbTable * @copyright Copyright (c) 2010 SetucoCMS Project.(http://sourceforge.jp/projects/setucocms) * @license http://www.opensource.org/licenses/gpl-2.0.php GNU General Public License, version 2 * @version * @link * @since File available since Release 0.1.0 * @author charlesvineyard */ /** * @package Common_Model * @subpackage DbTable * @author charlesvineyard */
adminモジュールのmediaコントローラーのindexアクションの場合
(ファイルの場所 application/modules/admin/views/scripts/media/index.phtml)
<?php /** * ファイルのアップロードや編集、一覧表示の画面 * * LICENSE: ライセンスに関する情報 * * @category Setuco * @package Admin * @subpackage View_Script_Media * @license http://www.opensource.org/licenses/gpl-2.0.php GNU General Public License, version 2 * @copyright Copyright (c) 2010 SetucoCMS Project.(http://sourceforge.jp/projects/setucocms) * @link * @version * @since File available since Release 0.1.0 * @param Setuco_Form $uploadForm ファイルをアップロードするフォーム * @author akitsukada */ ?>
Viewには、どの変数がわたされたかを "@param" のアノテーションに書いてください。
"@license"アノテーションは、"適用しているライセンス原文のURL ライセンス名"になります。
SetucoCMSではGPLv2を採用していますので、"@license http://www.opensource.org/licenses/gpl-2.0.php GNU General Public License, version 2"と記載します。
"@copyright"アノテーションの値は、常に"Copyright (c) 2010 SetucoCMS Project.(http://sourceforge.jp/projects/setucocms)"になります。
"@link"アノテーションは、"PHPDocumentorで生成したドキュメントのトップページURL"になります。
現在その場所を準備中であるため、それまでの間は"@link"とだけ記載します。
"@version"アノテーションに記載する文言は現在検討中であるため、文言決定までの間は"@version "とだけ記載します。
"@since"アノテーションは、"ファイルが作成されたバージョン"になります。
1stリリースまでの間に作成したファイルは、"@since File available since Release 0.1.0"と記載します。
"@category"アノテーションの値は、常に"Setuco"になります。
"@package"には"モジュール名"を記載します。SetucoCMSのモジュール名は、Admin、Common、Defaultなどです。
例えば、application/modules/admin/controllers/IndexController.phpであれば、モジュールにあたるディレクトリは「admin」ですから、"@package Admin"となります。ディレクトリ名は小文字ですが、@packageアノテーションでは先頭や単語の区切りを大文字にします（キャメルケース）。
書き方に迷ったら、同じディレクトリにある他のファイルを参照してみてください。同じディレクトリにあるクラスファイルの"@package"と"@subpackage"は、基本的に同じになります。
"@subpackage"は、モジュールの下にあるサブディレクトリを記載します。
例えば、application/modules/admin/controllers/IndexController.phpであれば、モジュールはadmin（つまり"@package"はAdmin）で、それ以下のパスはcontrollers/IndexController.phpですから、"@subpackage"は"Controller"となります。
application/modules/default/views/scripts/index/index.phtmlであれば、モジュールはdefaultで、それ以下のパスはviews/scripts/index/index.phtmlですから、"@subpackage"は"View_Script_Indexとなります。
ディレクトリ名は小文字だったり複数形だったりしますが、@subpackageアノテーションでは先頭と単語の区切りを大文字にし、複数形ではなく単数形で記載します。
application/modules/admin/models/DbTable/Site.phpのように、モジュール以下にサブディレクトリが複数有る場合は、それらを"@subpackage Model_DbTable"のようにアンダースコアでつなげて書きます。
既にあるメソッドを新たに編集した人は、 "@author" に半角スペースを空けて自分のアカウント名を追記してください。
たとえば、
* @autor suzuki-mar charlesvineyard akitsukada
のように、編集者名を連ねていきます。
[PageInfo]
LastUpdate: 2010-09-12 14:18:17, ModifiedBy: mars-3
[License]
Creative Commons 2.1 Attribution-ShareAlike
[Permissions]
view:all, edit:members, delete/config:members