Dokumentieren mit PLDoc

Dokumentieren ist ja bekanntlich nur etwas für Warmduscher und Hotel-Fluchtplan-Leser. Für eingefleischte Hardcore-Programmierer bietet das Open Source Werkzeug PLDoc die Möglichkeit, HTML Dokumentationen aus PL/SQL Programmen zu generieren.

Pate für das Open Source Projekt stand das viel genutzte Javadoc. Mit ihm ist es möglich, direkt aus dem Programmcode eine Dokumentation zu generieren. Der Programmierer muss mittels spezieller Schlüsselwörter innerhalb der Kommentare des Programmtextes eine Beschreibung von Prozeduren, Funktionen, Parametern und Variablen hinterlegen. Das Programm PLDoc untersucht den Programmcode und generiert daraus eine anschauliche Dokumentation auf Basis von HTML.

Wie geht’s

Kommentiert kann innerhalb oder außerhalb der PL/SQL Pakete werden. Der Autor bevorzugt die Kommentierung im Programmcode selbst, so dass dieser nicht verloren gehen kann. Von den zahlreichen Varianten und Schlüsselwörtern stellt dieser Artikel eine exemplarische Auswahl vor.

Die Dokumentation von PL/SQL Paketen findet grundsätzlich im Package Header statt. Der Package Body lässt sich nicht einbinden.

Das Listing 1 zeigt die Dokumentation einer Paket Spezifikation, welche mit dem Schlüsselwort @headcom abgeschlossen wird.

Listing 1: Die Dokumentation einer Paket Spezifikation, die mit dem Schlüsselwort @headcom abgeschlossen wird (Abbildung vergrößern!).

Das Listing 2 zeigt die wichtigsten Schlüsselwörter zur Beschreibung von Prozeduren und Funktionen.

Listing 2: Die wichtigsten Schlüsselwörter zur Beschreibung von Prozeduren und Funktionen (Abbildung vergrößern!).

Diese sind

• @param zur Dokumentation von Übergabeparametern,
• @return für die Beschreibung des Return Wertes bei Funktionen und
• @throws zur Bekanntmachung von Exceptions.

Besonders Vorteilhaft ist die Möglichkeit, in der Dokumentation selbst HTML Code zu verwenden. So lassen sich einzelne, wichtige Wörter wie commit farblich markieren oder die Änderungshistorie als Tabelle darstellen (siehe auch Listing 1).

Los geht’s

Mit dem folgenden Aufruf wird die Dokumentation schließlich generiert:

Die Option –d legt das Verzeichnis fest, in dem die HTML Dokumente generiert werden. Die Option –doctitle legt, wie sich leicht erraten lässt, die Überschrift der Dokumentation fest. –overview legt eine optionale Startseite fest und der letzte Parameter gibt die Datei oder die Dateien mit dem dokumentierten Programmcode an.

Listing 3: Die Rückgabe des Programmaufrufs.

Das Listing 3 zeigt die Rückgabe des Programmaufrufs. Die Abbildungen 1 und 2 zeigen das Ergebnis der Dokumentation aus Listing 1 und 2.

Abb. 1: Ergebnis der Dokumentation aus Listing 1 (Abbildung vergrößern!).

Abb. 2: Ergebnis der Dokumentation aus Listing 2 (Abbildung vergrößern!).

Quelle und Installation

Das Programm PLDoc liegt momentan in der Version 0.8.2 vor. Die 2,6 MB große Installationsdatei pldoc-0.8.2.zip beinhaltet alle notwendigen Programme und die Dokumentation.

Die jeweils aktuellste Version ist unter der Adresse http://pldoc.sourceforge.net/ zu finden.

Die Installation gestaltet sich ausgesprochen einfach. Auf dem Rechner muss die Java Runtime Version 1.2 vorhanden sein. Anschließend ist die ZIP Datei zu entpacken und los geht’s.

Eine gute Dokumentation wird in der ZIP Datei direkt mitgeliefert.

Fazit

Das Programm liefert auch bei mehreren Dutzend PL/SQL Paketen und mehreren tausend Zeilen Programmcode in weniger als einer Minute eine gut strukturierte Dokumentation. Dies allerdings nur auf Englisch.

Daneben ermöglicht auch die Dokumentation von SQL*Plus Skripten die Verwendung eigener Style Sheets (CSS) und vieles mehr. Schön wäre es, wenn auch der Code selbst eingebunden werden könnte. Dies entspricht aber nicht dem Konzept von javadoc und ist daher auch nicht Bestandteil von PLDoc.

Für den Inhalt der Dokumentation ist nach wie vor der Programmierer verantwortlich, der hoffentlich kalt geduscht hat und mit kühlem Kopf auch schwierige Sachverhalte anschaulich zu beschreiben weiß.

Martin Hoermann (info@ordix.de).

Seitenanfang

Seite drucken

Seite weiterempfehlen