ヘッダコメントブロック

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 タグを複数書くのではなく、コンマで区切って記述します。。

@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マニュアル \| PEARマニュアル \| Smarty(英語)マニュアル \| PHP-GTKマニュアル \| 「ヘッダコメントブロック」をGoogle検索
copyright © 1997-2024 PHP ドキュメント作成グループ(ライセンス). provided by php spot.	マニュアル：

ヘッダコメントブロック

内容を変更する必要のある必須タグ

任意タグ

文字間隔ほか

@package_version@ の使用法

移行ポリシー