Header Comment Blocks

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 version 5 * * LICENSE: This source file is subject to version 3.01 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_01.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_01.txt PHP License 3.01 * @version SVN: $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.*/

The following must be used in both the page-level and
class-level docblocks. Of course, change
"PackageName" to the name of your package.
This ensures the generated documentation links back your package.

* @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 Tags

@copyright

Feel free to apply whatever copyrights you desire.
When formatting this tag, the year should be in
four digit format and if a span of years is involved,
use a hyphen between the earliest and latest year.
The copyright holder can be you, a list of people, a
company, the PHP Group, etc. Examples:

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:

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 and Unreleased Packages

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