Problem

The current "Header Comment Blocks" portion of the Coding Standards was basically copied from PHP sources without alteration. Those headers are often construed to indicate that the license summary for the PHP License and the PHP Group copyright must be included in each file, even if a different license and/or copyright are used.

In addition, the header comments aren't parseable by phpDocumentor.

Solution

The following text shall become the new PEAR coding standard for header comment blocks.

===========================================

New Text

All source code files in the PEAR repository shall contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class. Below are examples of such docblocks.

<?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.

/**
 * 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
{
}
?>

Required But Variable

Short Descriptions

Short descriptions must be provided for all docblocks. They should be a quick sentence, not the name of the item. Please read the Coding Standard's sample file about how to write good descriptions.
http://pear.php.net/manual/en/standards.sample.php

PHP Versions

.
 * PHP version 4
 * PHP version 5
 * PHP versions 4 and 5

@license

.
 * @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.gnu.org/copyleft/lesser.html  LGPL License 2.1
 * @license   http://www.php.net/license/3_0.txt  PHP License 3.0

For more information, see the PEAR Group's Licensing Announcement:
http://pear.php.net/group/docs/20040402-la.php

@link

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

@author

There's no hard rule to determine when a new code contributor should be added to the list of authors for a given source file. In general, their changes should fall into the "substantial" category (meaning somewhere around 10% to 20% of code changes). Exceptions could be made for rewriting functions or contributing new logic.

Simple code reorganization or bug fixes would not justify the addition of a new individual to the list of authors.

@since

This tag is required when a file or class is added after the package's initial release. Do not use it in an initial release.

@deprecated

This tag is required when a file or class is no longer used but has been left in place for backwards compatibility.

Optional

@copyright

.
 * @copyright 2003 John Doe and Jennifer Buck
 * @copyright 2001-2004 John Doe
 * @copyright 1997-2004 The PHP Group
 * @copyright 2001-2004 XYZ Corporation

License Summary

If you are using the PHP License, use the summary text provided above. If another license is being used, please remove the PHP License summary. Feel free to substitute it with text appropriate to your license, though to keep things easy to locate, please preface the text with "LICENSE: ".

@see

Add a @see tag when you want to refer users to other sections of the package's documentation. If you have multiple items, separate them with commas rather than adding multiple @see tags.

Order and Spacing

To ease long term readability of PEAR source code, the text and tags must conform to the order and spacing provided in the example above. This standard is adopted from the JavaDoc standard.

@package_version@ Usage

There are two ways to implement the @package_version@ replacements. The procedure depends on whether you write your own package.xml files or if you use the PackageFileManager.

For those authoring package.xml files directly, add a <replace> element for each file. The XML for such would look something like this:

<file name="Class.php">
  <replace from="@package_version@" to="version" type="package-info" />
</file>

Maintainers using the PackageFileManager need to call addReplacement() for each file:

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

Transition Policy

Existing Small Packages

Existing packages that have only a few files are required to adopt these docblocks before the next release.

Existing Large Packages

Existing packages with many files are encouraged to adopt the new headers as soon as possible. When such packages come out with a new major version upgrade, these docblocks must be implemented therein.

New Packages

New packages and existing packages which have no releases yet must include these docblocks before their first release.

===========================================

Comments on the pear-dev Mailing List Regarding This RFC

• There were several comments about what to put in the @version tags. The current draft of this proposal uses the CVS "Id" tag for the "page-level" docblock which covers the file, while the class-level docblocks will use @package_version@, which gets replaced with the release's version number by the PEAR installer. This seems the best compromise because $Id$'s talk about files while the release version numbers talk about the classes. $Id$ is used rather than $Revision$ or other shorter tags because it is the standard and provides all of the potentially desired information.