< Dateitypen und Coding-Style | Entwicklungs-HOWTO | Die wichtigsten Klassen und Funktionen >
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
*/
Nächste Seite HowToMainStructures