Kommentare
Sie müssen vollständige Inline-Dokumentation bereitstellen (Docblocks).
Sie sollten auch abseits der offziellen API-Dokumentation Kommentare im Quellcode einsetzen. Als Daumenregel gilt, wenn Sie auf einen Code-Abschnitt schauen und denken: „Wow, Ich würde nicht versuchen herauszufinden, wie es funktioniert“, sollten Sie auf jeden Fall einen Kommentar ergänzen, bevor Sie vergessen, wie es funktioniert.
Kommentare im C-Stil (/* */) und von Standard-C++ (//) sollten verwendet werden. Kommentare im Perl/shell-Stil (#) sollten Sie vermeiden.
Kopf-Kommentare
Alle Quellcode-Dateien sollen einen „Page-level“ Docblock am Datei-Anfang besitzen und einen „Class-level“ Docblock unmittelbar vor jeder Klasse.
Beispiele:
<?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.
* 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.
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
@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');
?>
