PEAR リポジトリに含まれるすべてのソースコードには、 各ファイルの先頭に "ページレベル" のコメントブロックを、 各クラスの直前に "クラスレベル" のコメントブロックを記述します。 それらの例を示します。
<?php
/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
/**
* Short description for file
*
* Long description for file (if any)...
*
* PHP versions 4 and 5
*
* LICENSE: This source file is subject to version 3.0 of the PHP license
* that is available through the world-wide-web at the following URI:
* http://www.php.net/license/3_0.txt. If you did not receive a copy of
* the PHP License and are unable to obtain it through the web, please
* send a note to license@php.net so we can mail you a copy immediately.
*
* @category CategoryName
* @package PackageName
* @author Original Author <author@example.com>
* @author Another Author <another@example.com>
* @copyright 1997-2005 The PHP Group
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version CVS: $Id:$
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since File available since Release 1.2.0
* @deprecated File deprecated in Release 2.0.0
*/
/*
* Place includes, constant defines and $_GLOBAL settings here.
* Make sure they have appropriate docblocks to avoid phpDocumentor
* construing they are documented by the page-level docblock.
*/
/**
* Short description for class
*
* Long description for class (if any)...
*
* @category CategoryName
* @package PackageName
* @author Original Author <author@example.com>
* @author Another Author <another@example.com>
* @copyright 1997-2005 The PHP Group
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version Release: @package_version@
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class Foo_Bar
{
}
?> |
コメントブロックすべてに、Short descriptions （短い説明文）を記述します。 要素の名前ではなく、簡潔な文章で記します。良い説明文の書き方については、 サンプルファイル を参照してください。
PHP のバージョンについては、ページレベルのコメントブロックに 次のいずれかを記します
PEAR で利用できるライセンスには何種類かあります。 次のいずれかを選択し、ページレベルもしくはクラスレベルのコメントブロックに 記述します。
* @license http://www.apache.org/licenses/LICENSE-2.0 Apache License 2.0 * @license http://www.freebsd.org/copyright/freebsd-license.html BSD License (2 Clause) * @license http://www.debian.org/misc/bsd.license BSD License (3 Clause) * @license http://www.freebsd.org/copyright/license.html BSD License (4 Clause) * @license http://www.opensource.org/licenses/mit-license.html MIT License * @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1 * @license http://www.php.net/license/3_0.txt PHP License 3.0 |
詳細については、PEAR グループによるアナウンス Licensing Announcement （英語）を参照してください。
ページレベル、クラスレベルどちらにも使用できます。 もちろん、"PackageName" は自分のパッケージ名に置き換えます。 このタグを使うことで、生成されたドキュメントが自分のパッケージにリンクする ことができるようになります。
ソースファイルの作者リストに、コード提供者の名前を追加するべきかどうか を定義する明確な規則はありません。一般的には、 "相当な" 部分（10%から20%のコード変更を意味します）の変更を 行った場合に、作者に加えるようです。 関数のリライトや新たなロジックの提供の場合には、例外もありえます。
簡単なコードの整理やバグ修正は、作者リストに 新たに人を追加するまでの理由にはなりません。
ファイルやクラスが、パッケージの初リリースの後で加えられた場合、 このタグを使用します。初リリースに際しては使用しません。
ファイルやクラスが、もはや使われなくなっているが、 互換性のため残されている場合にこのタグを使用します。
コピーライトは自由に記述してください。 形式としては、年は西暦 4 桁で、複数年にわたる場合は ハイフンを用いて始まりの年と終わりの年を結びます。 著作権者は、個人でも複数人でも会社名でも PHP Group 等でもかまいません。 例を示します。
PHP ライセンスを使用する場合は、上記に示した概要文を使ってください。 他のライセンスを使用する場合は、PHP ライセンスの概要文を削除し、 使用するライセンスに対応するものに置き換えます。 ただし、記述は簡潔にとどめ、また LICENSE: という テキストを前につけます。
ユーザにパッケージのドキュメントの他のセクションを参照してもらう場合に @see タグを用います。複数の参照項目を記述する場合には、@see タグを複数書くのではなく、 コンマで区切って記述します。。
PEAR のソースコードを読みやすくするため、 テキストやタグの順序や文字間隔は、前の例にしたがう必要があります。 これは、JavaDoc 標準を採用したものになっています。
@package_version@ 置換は、2つの方法で実行することができます。 package.xml を書いているか、PackageFileManager を使っているかに 依ります。
package.xml を作成するにあたって、<replace> 要素を 各ファイルに対して追加します。以下のような XML となります。
<file name="Class.php"> <replace from="@package_version@" to="version" type="package-info" /> </file> |
メンテナが PackageFileManager を使っている場合は、 各ファイルに対して addReplacement() を コールするようにします。
数個のファイルからなる既存のパッケージは、 次のリリースまでに上記の docblocks に対応する。
多くのファイルから構成される既存のパッケージは、 できるだけ早く上記の新ヘッダに対応することが望まれる。 メジャーバージョンを上げるような更新をする場合には、 上記の docblocks に必ず対応する。
新しいパッケージや、既存でも未リリースのパッケージは、 初リリースまでに上記の docblocks に対応する。