< Dateitypen und Coding-Style | Entwicklungs-HOWTO | Grundgerüst einer Datei im public-Zweig >

1.  Offizielle API-Dokumentation

Die offizielle API-Dokumentation kann unter der URL:

http://hilfe.studip.de/api

eingesehen werden. Diese wird alle 15 Minuten aus dem trunk generiert. Verwendet wird dafür das Werkzeug doxygen, was (anders als phpdoc) schnell und zuverlässig aus dem Quellcode die API-Dokumentation erzeugt. In der dortigen Sidebar befinden sich folgende Auflistungen:

Data Structures

vorhandene Klassen

Class Hierarchy

Klassen hierarisch nach Inheritance gruppiert

Data Fields

Klassen- und Instanzvariablen

File List

alle Dateien

Directory Hierarchy

aufgeklappte Verzeichnisstrukturen

Examples

Liste aller in den Kommentaren enthaltenen Beispiele

Globals

Liste aller globalen Variablen und Funktionen

2.  Erzeugen der Dokumentation

Im trunk liegt ein Makefile mit Target "doc", so dass der folgende Aufruf:

1 ~ % make doc

im Verzeichnis die entsprechende API-Dokumentation frisch erzeugt.

Voraussetzung dafür ist die Installation von doxygen. Verwendet man Linux, kann man doxygen meist einfach über die Paketverwaltung installieren. Unter Ubuntu reicht dort zum Beispiel:

2 ~ % sudo apt-get install doxygen

Grundsätzlich kann doxygen auch für Unix, Mac und Windows aus den Quellen installiert werden. Eingehender dazu informiert die englische Anleitung.

Die Konfiguration für die Erzeugung befindet sich in tools/Doxyfile. Besonders einfach lässt sich diese mit doxywizard erzeugen.

3.  Wie schreibe ich API-Dokumentation?

Wer schon einmal mit @phpdoc@ oder @javadoc@ gearbeitet hat, kennt sich praktisch schon aus. Selbstverständlich gibt es auch noch doxygen eigene Spezifika, die weiter unten erläutert werden. Zunächst aber einige Best Practices, wie dokumentiert werden soll.

3.1  Top/Datei-Level-Kommentare

Jede PHP-Datei außerhalb von /template muss mit einem Copyright-Vorspann und einer Beschreibung des Inhalts der Datei eingeleitet werden:

/**
 * filename - Short description for file
 *
 * Long description for file (if any)...
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of
 * the License, or (at your option) any later version.
 *
 * @author      name <email>
 * @license     http://www.gnu.org/licenses/gpl-2.0.html GPL version 2
 * @category    Stud.IP
 */

3.2  Class-Kommentare

Jede Klasse muss einen Docblock haben, der den Nutzen und(!) die Verwendung beschreibt.

/**
 * This class provides a singleton instance that is used to manage PDO database
 * connections.
 *
 * Example of use:
 *
 *   # getting a PDO connection
 *   $key = 'studip';
 *   $db = DBManager::get($key);
 *   $db->query('SELECT * FROM user_info');
 *
 *   # setting a PDO connection
 *   $manager = DBManager::getInstance();
 *   $manager->setConnection('example', 'mysql:host=localhost;dbname=example',
 *                           'root', '');
 *
 **/

Wenn die Klasse schon ausführlich im Top-Level-Kommentar beschrieben wurde, darf man stattdessen dorthin verweisen: "für eine ausführliche Beschreibung siehe Kommentar am Anfang dieser Datei".

3.3  Methoden- und Funktionskommentare

Jede Funktion und Methode muss einen Docblock haben, der beschreibt, was die Funktion/Methode tut und wie man sie verwendet. Die Kommentare sollten deskriptiv ("Opens the file") und nicht imperativ ("Open the file") sein. Für gewöhnlich braucht der Kommentar nicht beschreiben, wie die Funktion funktioniert. Solche Kommentare sollten direkt im Quelltext stehen.

Die folgenden Dinge sollten im Kommentar enthalten sein:

• eine Beschreibung der Funktion
• alle Argumente und ihre Beschreibung
• alle möglichen Rückgabewerte und ihre Beschreibung
• ob und wann die Funktion Exceptions wirft

Es müssen ganze Sätze verwendet werden. Funktionen sollten ebenso wie Klassen deskriptiv (in dritter Person) kommentiert werden.

Wenn Getter/Setter-Methoden, Konstruktoren oder Destruktoren nichts unerwartetes tun, darf die Beschreibung der Funktion/Methode weggelassen werden.

    /**
     * Returns the value of the selected query parameter as a string.
     *
     * @param string $param    parameter name
     * @param string $default  default value if parameter is not set
     *
     * @return string  parameter value as string (if set), else NULL
     */

3.4  Property Comments

TODO

4.  Besonderheiten

4.1  Codebeispiele

Codebeispiele können ganz einfach in einen Kommentar einfügt werden, indem man semantisch den Bereich mit @code und @endcode einschliesst. Beispielsweise enthält die Datei DBManager folgenden Kommentar:

/**
 * This class provides a singleton instance that is used to manage PDO database
 * connections.
 *
 * Example of use:
 * @code
 *   # get hold of the DBManager's singleton
 *   $manager = DBManager::getInstance();
 *
 * [...]
 *
 * @endcode
 */

Letzte Änderung am 02.04.2011 01:53 Uhr von tthelen.