3.6. Dokumentations-Standards

Nicht nur beim Code, sondern auch bei der Dokumentation gibt WordPress im Handbuch einige Regeln vor. Plugin-Entwicklern wird nahegelegt, sich daran zu halten, da auf diese Weise nicht nur einem selbst, sondern auch anderen Programmierern geholfen wird, sich schnell zurecht zu finden.

Im Grunde orientiert sich das WordPress Dokumentations-Schema direkt an dem von PHPDoc (http://www.phpdoc.org). Während das Core Contributor Handbuch von WordPress jedoch nur Ergänzungen oder Abänderungen bespricht, findet man bei Github weitere Empfehlungen und Vorschläge zur Dokumentation der eigenen PHP-Scripte: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md.

Tipps zur Dokumentation

  1. Es sollte zu jeder Zeit klar sein, was eine Funktion macht, wann sie ausgeführt wird und warum. Dies gilt natürlich auch für WordPress Actions sowie Filter, die wir später besprechen werden.
  2. Weiter wird empfohlen, das @since-Tag zu benutzen. Es gibt an, ab welcher Version eine Klasse, eine Funktion oder eine Datei im eigenen Plugin existiert. Das hilft übrigens später ungemein, wenn Sie für Ihre eigenen Plugins Support leisten müssen.
  3. Benutzen Sie das Minuszeichen (-) um Aufzählungen zu generieren.
  4. Wenn Sie Codebeispiele angeben möchten, rücken Sie jede Code-Zeile mit jeweils 4 Leerzeichen ein. Vor und nach dem Code-Block muss sich eine Leerzeile befinden.

Funktionen und Methoden

Der Dokumentationsblock von Funktionen und Klassen sollte wie folgt aussehen:

  • Zusammenfassung
    Ein Einzeiler der beschreibt, was die Funktion/Klasse tut. Der Satz muss mit einem Punkt enden und darf keine HTML-Codes enthalten.
  • Beschreibung
    Eine ausführliche Beschreibung der Funktion, Methode, Klasse. Endet ebenfalls mit einem Punkt und darf – außerhalb von Codebeispielen – keine HTML-Tags enthalten.
  • @since
    Gibt die Versionsnummer mit einer optionalen Beschreibung an. Sie sollte dreistellig sein. Mehrere @since-Blöcke sollte es geben, sobald signifikante Änderungen durchgeführt wurden.
  • @access
    Soll nur bei Methoden in Klassen benutzt werden. Und auch nur dann, wenn die Methode als private markiert ist.
  • @see
    Beschreibt eine Funktion, eine Methode oder eine Klasse, auf die aufgebaut oder verweisen wird. Alternativ kann hier auch eine URL eingegeben oder auf einen Cook verweisen werden ({@see 'save_post}.
  • @deprecated
    Bedeutet “veraltet” und wird nur angegeben, wenn die Klasse, die Funktion oder die Methode nicht mehr verwendet werden soll. Dahinter wird die dreistellige Versionsnummer angegeben, ab welcher Version sie als veraltet markiert wurde. Zum Schluss ist noch eine kurze Beschreibung sinnvoll, die angibt, welche Funktion stattdessen Verwendung finden soll.
  • @link
    Wurde früher für das Setzen von Links benutzt. Dies ist in PHPDoc jedoch mittlerweile veraltet. Man sollte stattdessen das @see verwenden, welches ebenfalls auf URLs verweisen kann.
  • @global
    Listet alle globalen Variablen auf, die innerhalb der Funktion bzw. der Methode zur Anwendung kommen.

Code-Schnipsel:

<?php
/**
 * Zusammenfassung
 *
 * Beschreibung.
 *
 * @since x.x.x
 * @since x.x.x Änderung Y.
 * @deprecated x.x.x Benutze stattdessen neuer_funktionsname().
 * @access (für Methoden nur wenn als privat markiert)
 *
 * @see Function/method/class relied on
 * @global Typ $var Kurzbeschreibung.
 *
 * @param  Typ $var Beschreibung.
 * @param  Typ $var Optional. Beschreibung.
 *
 * @return Typ Beschreibung.
 */
 ?>

Beispiel

<?php
/**
 * Lässt das Fahrzeug fahren.
 *
 * Legt den ersten Gang des Fahrzeugs ein und beschleunigt.
 *
 * @since 1.0.3
 *
 * @see   Fahrzeug::fahren()
 *
 * @param object $fahrzeug Eine Klasse des Typs Fahrzeug.
 * @param int    $gang Optional. Der Gang der eingelegt werden soll.
 *
 * @return float Geschwindigkeit
 */
function fahren( $fahrzeug, $gang = 1 ) {

	$fahrzeug->gang_einlegen( $gang );

	return $fahrzeug->geschwindigkeit();
}

?>

Auf Github ansehen

Klassen

Klassen-Eigenschaften sollten wie folgt deklariert werden:

  • Zusammenfassung
    Der Satz sollte mit einem Punkt enden.
  • @since
    Gibt die Versionsnummer mit einer optionalen Beschreibung an. Sie sollte dreistellig sein.
  • @access
    Gibt an, ob eine Eigenschaft als private, protected oder public markiert wurde.
  • @var
    Wie @param.

Code-Schnippsel:

<?php
/**
 * Zusammenfassung.
 *
 * @since x.x.x
 * @access (private, protected, or public)
 * @var Typ $var Beschreibung.
 *
 */
 ?>

Beispiel:

<?php
class Meine_Klasse {
	/**
	 * Prüft ob Motor gerade läuft.
	 *
	 * @since  1.0.0
	 * @access private
	 * @var bool $running
	 */
	private $running = false;
}
?>

Auf Github ansehen

Einbinden von Dateien

Dateien, die mit include oder require eingebunden werden, sollten durch eine kleine Kurzbeschreibung ergänzt werden.

<?php
/**
 * Kurzbeschreibung.
 */
 require_once( ABSPATH . '/dateiname.php' );
?>

Hooks (Actions & Filter)

Wenn Sie eigene Filter (apply_filters) oder Actions (do_action) in Ihrem Plugin nutzen, so sollten diese dort kommentiert werden, wo sie Anwendung finden.

  • Zusammenfassung
    Sollte mit einem Punkt enden.
  • Beschreibung
    Falls nötig eine ausführliche Beschreibung der Aktion oder des Filters. Endet ebenfalls mit einem Punkt.
  • @since
    Gibt die Versionsnummer mit einer optionalen Beschreibung an. Sie sollte dreistellig sein.
  • @param
    Wenn eines der Parameter ein Array übergibt, sollte dieses mittels der PHPDoc Hash-Annotation beschrieben werden.
  • @ignore
    Gibt an, ob ein Hook nur für interne Zwecke Verwendung finden sollte.

Achtung: @return wird nur bei Filtern angegeben. Sie geben immer den ersten Eingangsparameter zurück. Actions haben keinen Rückgabewert.

<?php
/**
 * Zusammenfassung.
 *
 * Beschreibung.
 *
 * @since x.x.x
 *
 * @param array $args {
 *      Kurzbeschreibung
 *      @type type $var Description.
 *      @type type $var Description.
 * }
 * @param  Typ $var Beschreibung.
 */
 do_action( 'mm_tue_etwas', $array, $boolean );
 ?>

Filter und Actions werden in der Regel öfter als nur einmal angewendet. Ist das der Fall, muss nicht immer der komplette PHPDoc-Block wiederholt werden. Stattdessen ist es besser, den kompletten Block nur beim ersten Vorkommen zu dokumentieren und dann darauf zu verweisen.

<?php
/** Diese Aktion wurde in Pfad/zur/dateiname.php bereits dokumentiert. */
do_action( 'mm_tue_etwas', $array, $boolean );
?>

Kommentare

Kommentare, die direkt im PHP Code angegeben werden, sollten wie folgt dokumentiert werden.

<?php
// Einzeiliger Kommentar.

/**
 * Dieser Kommentar ist lang genug, dass  
 * er sich über mehrere Zeilen erstreckt.
 */
?>

Dokumentation von Dateien

Im Kopfbereich einer Datei sollte die Dokumentation wie folgt aussehen:

  • Zusammenfassung
    Sollte mit einem Punkt enden und zusammenfassen, welchen Zweck die aktuell vorliegende Datei erfüllt.
  • Beschreibung
    Falls nötig eine ausführliche Beschreibung der Datei. Endet ebenfalls mit einem Punkt.
  • @since
    Gibt die Versionsnummer mit einer optionalen Beschreibung an. Sie sollte dreistellig sein.
  • @see
    Beschreibt eine Funktion, eine Methode oder eine Klasse, auf die aufgebaut wird. Alternativ kann hier auch eine URL eingegeben werden.
  • @package
    Ein sogenanntes Package kann dazu verwendet werden, verwandte Elemente zu gruppieren.
  • @subpackageWerden dazu benutzt, Elemente in Untergruppen einzuteilen. Oft werden hier auch die PHP Namespaces angegeben.
<?php
/**
 * Zusammenfassung.
 *
 * Beschreibung.
 *
 * @since x.x.x
 * @see URL
 *
 * @package WordPress
 * @subpackage Komponent
 */
 ?>

Konstanten

  • Zusammenfassung
    Sollte mit einem Punkt enden.
  • @since
    Gibt die Versionsnummer mit einer optionalen Beschreibung an. Sie sollte dreistellig sein.
  • @var
    Angabe von Typ und Beschreibung.
<?php
/**
 * Kurzbeschreibung.
 *
 * @since x.x.x
 * @access (private, protected, or public)
 * @var Typ $var Beschreibung.
 *
 */
 ?>

Beispiel:

<?php
class Meine_Klasse {
	/**
	 * Wert für den Start.
	 *
	 * @since  1.0.0
	 * @access public
	 * @var int
	 */
	const START = 0;
}
?>

Auf Github ansehen

Häufig verwendete PHPDoc-Blocks in WordPress

  • @access
    Benutzung: public, private oder protected
    Definiert die Zugriffssteuerung auf Funktionen und Methoden. @access private bedeutet, dass die Funktion/Methode nicht dokumentiert werden soll, da sie nicht für den öffentlichen Einsatz erstellt wurde.
  • @deprecated
    Benutzung: x.x.x Neuer Funktionsname
    Gibt an, ab welcher Version des Plugins die Funktion für veraltet erklärt wurde. Sollte dreistellig sein.
  • @global
    Benutzung: [Typ] $GLOBALS['varname']
    Gibt an, ob eine globale Variable verwendet wurde.
  • @internal
    Benutzung: [Beschreibung]
    Kann für interne Anmerkungen benutzt werden.
  • @ingore
    Benutzung: steht für sich allein.
    Wenn das aktuelle Element komplett übersprungen werden soll (d.h. nur interne Nutzung).
  • @link
    Benutzung: [URL]
    Sollte nicht mehr benutzt werden, da veraltet. Nutzen Sie stattdessen @see.
  • @method
    Benutzung: [Typ] [Beschreibung]
    Gibt eine magische Funktion innerhalb einer Klasse an.
  • @package
    Benutzung: [Paketname]
    Spezifiziert ein Paket, zu dem die Funktionen und Konstanten gehören.
  • @param
    Benutzung: [Typ] $varname [Beschreibung]
    Parameter einer Funktion oder einer Methode.
  • @return
    Benutzung: [Typ] [Beschreibung]
    Dokumentiert den Rückgabewert einer Funktion oder einer Methode.
  • @see
    Benutzung: [Elementname]
    Referenziert eine andere Methode, Funktion oder Klasse, auf die aufgebaut wird. Alternativ kann auch eine URL als Verweis angegeben werden.
  • @since
    Benutzung: x.x.x [Beschreibung]
    Dokumentiert, ab wann eine Funktion/Methode/Klasse zum Plugin hinzugefügt wurde. Sollte dreistellig sein.
  • @subpackage
    Benutzung: [Name]
    Spezifiziert eine Komponente, zu der alle Funktionen und Methode gehören.
  • @todo
    Benutzung: [Beschreibung]
    Beschreibt zukünftige Änderungen.
  • @type
    Benutzung: [Typ] [Beschreibung]
    Wird für die Typenbezeichnungen von Array-Werten benutzt.
  • @uses
    Benutzung: klasse:methode() oder klasse::$variable oder funktionsname().
  • @var
    Benutzung: [Typ] [Beschreibung]
    Datentyp für eine Klassenvariable sowie eine kurze Beschreibung dieser.
❬ 3.5. Coding Standards3.7. Präfixe und Entwurfsmuster ❭