mijane Blog

Wie bereits angekündigt, habe ich beschlossen eine Serie zu dem Thema Doc Blocks in PHP zu starten. Als Doc Block System habe ich mir phpDocumentor ausgesucht, da ich hiermit schon länger arbeite und phpDocumentor alles benötigte bereit stellt.

Starten, werde ich logischerweise mit der Installation von phpDocumentor. Die Installation lässt sich wirklich einfach bewerkstelligen und bietet unter anderem eine Installation unter PEAR (so langsam liebe ich PEAR wirklich). Ihr könnt eure Dokumentationen über die Kommandozeile erstellen oder das Webinterface von phpDocumentor benutzen. In den nächsten beiden Blöcke werde ich auf die Erstellung der Dokumentation unter Benutzung der Konsole und danach durch das Webinterface eingehen.

"phpDocumentor installieren" vollständig lesen

Eine Serie zu einem bestimmtem Thema ist doch immer was nettes, so sehe ich das wenigstens. Also habe ich mir vorgenommen hier eine Serie zum Thema Doc Blocks in PHP zu starten.

Als Doc Block Engine habe ich mir phpDocumentor ausgesucht, da ich hiermit schon länger arbeite und ich dieses Tool ohne Einschränkung empfehlen kann. Ein Blick über den Tellerrand kann aber auch nicht schaden, also werden wir uns auch noch ein Paar andere Programme zur Quellcode Dokumentation anschauen. Vielleicht findet sich ja auch jemand der schon mit anderen Systemen wie z.B. Doxygen gearbeitet hat und gerne ein bisschen darüber erzählen möchte. Bei Interesse meldet euch bitte bei mir über das Kontakt - Formular oder über meine E - Mail Adresse aus dem Impressum.

Starten wir werden mit der Installation von phpDocumentor unter PEAR und als Web Interface. Danach gibt es eine kleine Einführung wie ihr den phpDocumentor auf der Kommandozeile ausführen könnt. Natürlich darf auch ein Einblick in die ganzen Doc Block Parameter nicht fehlen, die ich hier im Kommentar schon Angekündigt habe. Darauf wird eine kleine Session zu dem Thema Doc Block Formatierungen folgen, wo vielleicht auch einige von den erfahreneren Leser noch ein Paar neue Sachen kennen lernen können.

Ich glaube dass das ein ganz interessantes Thema werden wird. Ich persönlich freue mich schon darauf.

Je umfangreicher ein Projekt wird, desto wichtiger wird die Dokumentation. Kommentare helfen, den Programmcode besser zu verstehen. Nach einiger Zeit wissen selbst die Progammierer nicht mehr, was sie vor x Wochen oder Monaten geschrieben haben. Hier kommen die Doc Blocks ins Spiel. Jede Klasse und / oder Methode sollte mit einem Kommentar versehen werden.
Der eigentliche Quellcode sollte durch Aussagekräftige Variablen und Methoden selbst erklärend sein. Ich finde das, wenn man einen Kommentar in einer Methode oder Funktion benötigt, der Code zu umständlich geschrieben ist.

Was genau sollte ein Doc Block erklären? Hier folgt ein kleiner Überblick:

• welche Aufgabe hat die Funktion / Methode
• welche Parameter erwartet sie
• welchen Datentyp gibt sie zurück

Wie genau ist ein Doc Block aufgebaut?

/**
* Hier steht was genau in der Methode passiert
*
* @param int $sId
* @return string
*/

@param gibt an welche Parameter von der Methode benötigt werden.
@return gibt an welcher Typ von der Methode zurück gegeben wird

Der Doc Block wird direkt vor der Klasse oder der Methode angegeben und beginnt mit den Zeichen /**. Jede neue Zeile beginnt mit einem * und das Ende des Doc Blocks wird mit */ eingeleitet.

Eine Auflistung aller Doc Block Tags werde ich demnächst hier vorstellen.

Here is an little example how you can create your php doc block. This example is copied from the mijane files and it's included to an svn client:

/**
* ### short desc ###
*
* ### long desc ###
*
* PHP 5 // should be php 5
*
* @filesource $HeadURL$ // file path from svn
* @copyright Copyright (c) 2008, mijane // your copyright
* @link http://www.mijane.de // your website
* @package mijane_framework // package
* @sub-package core // subpackage
* @since 2008-11-21 // date of creation
* @version 0.0.1 // version like #.#.#
* @revision $Revision:$ // revision
* @author Peter Rother // author
* @modifiedby $Author$ // last committer
* @lastmodified $Date:$ // date
*/