PHPDoc - Wie man PHP Code effektiv dokumentiert

[Josh]

Hallo alle zusammen,

Ich wollte heute endlich einmal mich informieren, wie man effektiv seinen PHP Code dokumentiert.
Von Java her kenne ich die JavaDoc Kommentare, welche etwa so aussehen:

/** Dies ist ein Java Doc Kommentar */

Dazu gibt es noch viele Tags, mit welchen man wichtige Infos über seine Klassen, Funktionen, Konstanten etc. bereitstellten kann.
Weiter gibt es ein Tool namens JavaDoc, welches diese Kommentare parsed und daraus automatisch eine sehr gute Dokumentation mit allen Infos über Funktionen etc. in HTML, XML, PDF etc. erstellt. Dies sieht im Real Life etwa so aus:

http://java.sun.com/j2se/1.3/docs/api/

Equivalent zu JavaDOC wurde PHPDoc entwickelt, und ich habe mich heute darüber schlau gemacht, wie man PHPDoc effizient einsetzen kann.

Hier eine Beispielklasse für eine gute PHPDoc Doku:

<?php

/**
 * Eine Konstante...
 * @const
 */
define("MY_CONSTANT","Der Inhalt meiner Konstante");

/**
 * Hauptbeschreibung in nur einem Satz.
 *
 * Grosse Beschreibung in beliebig vielen Sätzen.
 *
 * @package myPackage
 *
 * @author Ich <meine@email.xx>
 * @copyright 200x
 * @version 1.111
 */
class XYZ() {

    /**
     * Dies ist eine Variable, welche Fliesskommazahlen speichert.
     * @var double
	 */
    var $myVar = "Inhalt meiner Var";

    /**
     * Dies ist der Konstruktor.
     *
     * Dieser Konstruktor tut dieses und jenes... Manchmal auch noch mehr...
     *
     * @param string $var Eine schöne Variable.
     */
    function XYZ($var) {
        // Code...
    }

    /**
     * Diese Funktion gibt die Variable <var>$diesUndDas</var> zurück.
     *
     * Dies und das kann dieses und jenes sein... Aber auch noch mehr...
     *
     * @param string $bla Eine schöne Variable.
     *
     * @return string Der zurückgegebene String.
	 *
     * @see getDiesesUndJenes()
     */
    function getDiesUndDas($bla) {
        // Code...
        return $diesUndDas;
    }

    /**
     * Diese Funktion gibt die Variable <var>$diesUndDas</var> zurück.
     *
     * Dies und das kann dieses und jenes sein... Aber auch noch mehr...
     *
     * @param string $bla Eine schöne Variable.
     *
     * @return string Der zurückgegebene String.
     *
     * @see getDiesUndDas()
     */
    function getDiesesUndJenes($bla) {
        // Code...
        return $diesUndDas;
    }
}

?>
[/code}

Und hier was dabei rauskommt:

[URL="http://phpmywebmin.josh.ch/_uploads/j0sh/XYZPHPDoc.zip"]http://phpmywebmin.josh.ch/_uploads/j0sh/XYZPHPDoc.zip[/URL]

Oder mit einem anderen Skin:

[URL="http://phpmywebmin.josh.ch/_uploads/j0sh/XYZPHPDoc.zip"]http://phpmywebmin.josh.ch/_uploads/j0sh/XYZPHPDoc.zip[/URL]

Schaut euch das Ganze mal an auf www.docbuilder.org ; nach einer kurzen Lernphase wird das ganz bestimmt ein sehr nützliches Tool für grössere PHP Projekte werden! [IMG]http://www.webmasterforum.ch/html/emoticons/smile.gif[/IMG]

Grüsse
Josh

 

[brauchli]

Ich mag so lange Kommentare überhaupt nicht. Doch jedes Script sollte kommentiert werden. Darum bevorzuge ich die "//" Methode pro Zeile.

Example:
$brutto_einkommen = 4005 //Ihr Einkommen ohne Sozialabzüge
$netto_einkommen = 3223 //Ihr Auszahlungsbetrag

Freundliche Grüsse

 

[Josh]

nun, brauchli, diese kommentare sollten sich natürlich in JEDEM script befinden. doch in obiger variante geht es darum, klassen und funktionen in einer sinnvollen struktur zu kommentieren, damit jeder, der die klasse verwenden will, mit dem generierten PHPDoc schnell sieht, wie er damit umgehen muss. hast du dir die zips angesehen?