Kopf-Kommentare

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 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
{
}

?>

Erforderliche Tags

Kurzbeschriebung

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.

PHP Version

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
@license

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.

@link

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
@author

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.

@since

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.

@deprecated

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.

Optionale Tags

@copyright

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

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.

Abfolge und Leerzeichen

Um die langfristige Lesbarkeit zu gewährleisten, sollten Texte und Tags dem gegebenem Beispiel folgen. Diese Festlegungen entsprechen dem JavaDoc-Standard.

Verwendung von @package_version@

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');
?>

Übergangsregeln

Für existierende kleine Packages

Existierende Packages mit nur wenigen Dateien sollten die DocBlöcke im nächst möglichen Release enthalten.

Für existierende große Packages

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 und unveröffentliche Packages

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.

PHP-Code-Tags (Previous) CVS-Nutzung (Next)
Last updated: Sun, 19 Dec 2010 — 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.