Alle Quellcode-Dateien im PEAR-Repository sollen einen "Page-level" Docblock am Datei-Anfang besitzen und einen "Class-level" Docblock unmittelbar vor jeder Klasse. Im Nachfolgenden verschiedene Beispiele dazu:
<?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 [email protected] so we can mail you a copy immediately.
*
* @category CategoryName
* @package PackageName
* @author Original Author <[email protected]>
* @author Another Author <[email protected]>
* @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 <[email protected]>
* @author Another Author <[email protected]>
* @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
{
}
?>
Die Kurzbeschreibung muss in allen Docblocks existieren. Sie umfasst einen Satz, und sollten keinesfalls nur aus dem Namen des beschreibenden Objektes stehen. In der Beispieldatei finden Sie entsprechende Demonstrationen.
Folgende Zeile muss in den Page-level-Docblock eingefügt werden. Sie beschreibt, unter welcher PHP-Version der Quellcode läuft:
. * PHP version 4 * PHP version 5 * PHP versions 4 and 5
Sie können verschiedene Lizenzen für ihr Package verwenden. Sie müssen eine auswählen und diese sowohl im Page-level-, wie auch dem Class-level-Docblock einfügen:
. * @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
Für weitere Informationen bezüglich der Lizenz lesen Sie auch das Licensing Announcement der PEAR-Group.
Die Link-Angabe muss im Page-level- and Class-level-Docblock erfolgen. Sie müssen den Eintrag für "PackageName" natürlich durch den Namen Ihres Packages ersetzen. Auf diese Weise ist sicher gestellt, dass die API-Dokumentation die Links auf die Package-Homepage enthält.
. * @link http://pear.php.net/package/PackageName
Es gibt keine klare Regel, wann jemand zur Liste der Quellcode-Autoren hinzugefügt werden sollte. Allgemein sollten sie substanziell beigetragen haben, ca. 10% bis 20% des Codes. Sie können Ausnahmen machen, wenn Methoden neu geschrieben wurden oder neue Logik beigesteuert wurde.
Einfache Code-Neuformatierungen oder Bug-Fixes sollten nicht zur Aufnahme in die Liste führen.
Dieses Tag ist erforderlich, wenn eine Datei oder Klasse nach dem ersten Release zum Package ergänzt wurde. Verwenden Sie es nicht beim ersten Release.
Dieses Tag ist erforderlich, wenn eine Datei oder Klasse nicht mehr benutzt wird, aber für die Rückwärtskompatibilität noch verfügbar ist.
Sie können dieses Tag setzen, wenn Sie Copyright-Anmerkungen ergänzen wollen. Das Format des Tags: Die vierstellige Jahreszahl bzw. bei mehreren Jahren, nur das erste und letzte Jahr getrennt mit einem Querstrich; danach der Copyright-Inhaber, also die betreffenden Personen, Firma oder z.B. die PHP Group. Beispiele:
. * @copyright 2003 John Doe and Jennifer Buck * @copyright 2001-2004 John Doe * @copyright 1997-2004 The PHP Group * @copyright 2001-2004 XYZ Corporation
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: .
Fügen Sie ein @see-Tag hinzu, wenn Sie auf andere
Abschnitte in der Package-Dokumentation verweisen. Wenn Sie mehrere
Einträge hinzufügen, verwenden Sie nicht mehrere Tags, sondern
trennen diese in einem Tag per Komma.
Um die langfristige Lesbarkeit zu gewährleisten, sollten Texte und Tags dem gegebenem Beispiel folgen. Diese Festlegungen entsprechen dem JavaDoc-Standard.
Es gibt zwei Wege @package_version@ zu ersetzen.
Das ist abhängig davon, ob Sie die Package-Datei
package.xml von Hand erzeugen oder das
Package PackageFileManager benutzen.
Wenn Sie die Datei direkt bearbeiten, ergänzen Sie ein <replace>-Tag für jede Datei. Das XML sieht dann ähnlich wie dieses aus:
<file name="Class.php"> <replace from="@package_version@" to="version" type="package-info" /> </file>
Wenn PackageFileManager verwenden, rufen Sie addReplacement() für jede Datei auf:
<?php
$pkg->addReplacement('filename.php', 'package-info',
'@package_version@', 'version');
?>
Existierende Packages mit nur wenigen Dateien sollten die DocBlöcke im nächst möglichen Release enthalten.
Existierende Packages mit vielen Dateien sollten die neuen DocBlöcke sobald wie möglich integrieren. Auf jeden Fall aber mit den nächsten Major-Release.
Neue Packages und existierende Package, für welche noch kein Release existiert, müssen über die DocBlöcke verfügen, wenn ihr erstes Release erscheint.