ヘッダコメントブロック

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:
<?php
$
?>
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

コメントブロックすべてに、Short descriptions (短い説明文)を記述します。 要素の名前ではなく、簡潔な文章で記します。良い説明文の書き方については、 サンプルファイル を参照してください。

PHP Versions

PHP のバージョンについては、ページレベルのコメントブロックに 次のいずれかを記します

* PHP version 4
 * PHP version 5
 * PHP versions 4 and 5
@license

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 (英語)を参照してください。

@link

ページレベル、クラスレベルどちらにも使用できます。 もちろん、"PackageName" は自分のパッケージ名に置き換えます。 このタグを使うことで、生成されたドキュメントが自分のパッケージにリンクする ことができるようになります。

* @link      http://pear.php.net/package/PackageName
@author

ソースファイルの作者リストに、コード提供者の名前を追加するべきかどうか を定義する明確な規則はありません。一般的には、 "相当な" 部分(10%から20%のコード変更を意味します)の変更を 行った場合に、作者に加えるようです。 関数のリライトや新たなロジックの提供の場合には、例外もありえます。

簡単なコードの整理やバグ修正は、作者リストに 新たに人を追加するまでの理由にはなりません。

@since

ファイルやクラスが、パッケージの初リリースの後で加えられた場合、 このタグを使用します。初リリースに際しては使用しません。

@deprecated

ファイルやクラスが、もはや使われなくなっているが、 互換性のため残されている場合にこのタグを使用します。

任意タグ

@copyright

コピーライトは自由に記述してください。 形式としては、年は西暦 4 桁で、複数年にわたる場合は ハイフンを用いて始まりの年と終わりの年を結びます。 著作権者は、個人でも複数人でも会社名でも PHP Group 等でもかまいません。 例を示します。

* @copyright 2003 John Doe and Jennifer Buck
 * @copyright 2001-2004 John Doe
 * @copyright 1997-2004 The PHP Group
 * @copyright 2001-2004 XYZ Corporation
ライセンスの概要

PHP ライセンスを使用する場合は、上記に示した概要文を使ってください。 他のライセンスを使用する場合は、PHP ライセンスの概要文を削除し、 使用するライセンスに対応するものに置き換えます。 ただし、記述は簡潔にとどめ、また LICENSE: という テキストを前につけます。

@see

ユーザにパッケージのドキュメントの他のセクションを参照してもらう場合に @see タグを用います。複数の参照項目を記述する場合には、@see タグを複数書くのではなく、 コンマで区切って記述します。。

文字間隔ほか

PEAR のソースコードを読みやすくするため、 テキストやタグの順序や文字間隔は、前の例にしたがう必要があります。 これは、JavaDoc 標準を採用したものになっています。

@package_version@ の使用法

@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() を コールするようにします。

<?php
$pkg
->addReplacement('filename.php''package-info',
                     
'@package_version@''version');
?>

移行ポリシー

既存の小規模なパッケージ

数個のファイルからなる既存のパッケージは、 次のリリースまでに上記の docblocks に対応する。

既存の大規模なパッケージ

多くのファイルから構成される既存のパッケージは、 できるだけ早く上記の新ヘッダに対応することが望まれる。 メジャーバージョンを上げるような更新をする場合には、 上記の docblocks に必ず対応する。

未リリースのパッケージ

新しいパッケージや、既存でも未リリースのパッケージは、 初リリースまでに上記の docblocks に対応する。

PHP コードタグ (Previous) CVS の使用 (Next)
Last updated: Sun, 23 Nov 2014 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

Note by: michael.spiess@cuxmedia.de
Im Beispiel ist unter anderem die Zeile:
* @version CVS: <?php
$
?>
Id:$
aufgeführt. Bei mir ergibt das aber keine Versionsausgabe, sondern nur das "$" Zeichen.

Ich arbeite mit Doxygen.

Gruß
Michael
Note by: frustrated@example.org
The name of the command for emitting docblock documentation should be mentioned.