Keine Angst vor der großen Doku

Wer kennt es nicht. Man steht vor einem Problem und weiß nicht mehr weiter. Der erste Weg ist warscheinlich das Fragen eines Kollegen oder eine Runde googlen. Man kämpft sich durch zahlreiche Foreneinträge, die mit den Worten Habe das Problem gelöst. enden, aber der Autor war zu faul, seinen Lösungsweg darunterzuschreiben. Hat man sich dann doch durchgerungen, einmal in die API reinzuschauen, wird man von Informationen geradezu erschlagen.

Den Überblick behalten

Es gibt verschiedene Arten, in der eine Dokumentation verfasst ist. Wollen wir uns nun einmal die verschiedenen Typen genauer anschauen.

Man-Pages

Unter den meisten Linux/BSD-Derivaten ist es üblich, Dokumentation in Form von Man(ual)-Pages zu verfassen. Diese können über die Console mit dem Befehl

man suchbegriff

aufgerufen werden. Daraufhin wird die ManPage für die aktuelle Größe des Terminalfensters formatiert und mit einem Textbetrachter (meist more oder less) geöffnet. Navigiert wird hier mit [Bild-Hoch], [Bild-Runter] bzw. [Leertaste] für seitenweises blättern und [Enter] für zeilenweises scrollen. Mit /suchbegriff kann nach einem bestimmten Begriff gesucht werden. Mit den Tasten [N] und [P] kann durch die Suchergebnisse springen.

Der Aufbau ist immer derselbe. Am oberen Rand sieht man die Bezeichnung und eine Zahl in Klammern. Diese gibt Auskunft darüber, in welcher Kategorie sich die Man-Page befindet (Mehr dazu). In der Übersicht wird der Befehl mit seinen möglichen Konstellationen und Parametern gezeigt. Darunter kommt ein kurzer Abriss über die Funktionalität und danach die eigentliche Beschreibung der Parameter und Funktionsweise. Zum Schluss werden meist noch ähnliche oder dazugehörige Man-Pages und Programmbeispiele aufgeführt. Wer es lieber etwas grafischer möchte, kann sich TkMan mal etwas näher anschauen. Die deutschen Man-Pages lassen sich ebenfalls bequem in das System einspeisen.

Doxygen, JavaDoc, Documentor

Eine bei größeren Programmen und Projekten sehr beliebte Dokumentationsart, da sie sehr wenig Zeit in Anspruch nimmt. Hier wird die Dokumentation direkt aus dem Programmcode erzeugt (dies geschieht über spezielle Doclet-Tags) und ist somit hauptsächlich dafür gedacht, den Programmcode zu verstehen bzw. sich in die API zu lesen. Die bekanntesten Systeme sind JavaDoc (Java), phpDocumentor (PHP), Doxygen (Java und andere objektorientierte Sprachen) und GtkDoc (C).

Erreichbar ist diese Dokumentation üblicherweise über einen Web-Browser. Die Darstellung und die Aufbereitung der Informationen sind bei den genannten Systemen ziemlich ähnlich: Man navigiert durch die einzelnen Klassen, sieht deren Attribute und Methoden. Wenn die Klasse abgeleitet wurde oder ein Interface implementiert hat, wird dies ebenfalls angezeigt. Doxygen geht hier noch weiter und erstellt hübsche UML-Diagramme aus den Klassenbeziehungen. Wenn der Programmierer eine Methode oder ein Attribut nach den Doclet-Regeln kommentiert hat, wird dieser Kommentar direkt übernommen und an der richtigen Stelle eingefügt und schick formatiert.

DocBook

DocBook wird häufig dann verwendet, wenn das Gesamtwerk beschrieben werden, sprich eine richtige Dokumentation in Textform verfasst werden soll. Hier wird mit Prev (zurückblättern) und Next (weiterblättern), sowie Home (Inhaltsverzeichnis) und Up (zur nächsthöheren Verzeichnisebene wechseln) navigiert.

Gelesen werden sollte diese meist von vorn nach hinten, da die einzelnen Kapitel aufeinander aufbauen. Das erfreuliche dabei ist, das in DocBook geschriebene Dokumentationen in viele verschiedene Ausgabeformate gebracht werden kann. So auch als PDF zum Ausdrucken oder auf den PDA laden.

Wikis

Diese Form von Dokumentation trifft man in letzter Zeit sehr häufig an. Besonders beliebt sind hier DokuWiki und MediaWiki. Diese Systeme sind sehr dynamisch, denn es wird ständig von vielen Menschen erweitert. Eine klare Struktur gibt es hier nie, doch wird hier meist nicht eine spezielle Klasse oder Funktion beschrieben, sondern eher ein Anwendungsfall. Die Aktualität der Informationen lässt sich meist über die Editierhistory nachprüfen und wenn man einen Fehler entdeckt hat, kann man diesen kurzerhand selbst beheben.

Richtig anwenden

So, die Information ist gefunden, doch wie wende ich diese an? Machen wir ein kleines Beispiel: Wir sind gerade dabei, einen Download-Manager in Java zu programmieren und suchen jetzt eine Anleitung, wie man mehrere Downloads gleichzeitig starten kann.

Zuerst gehen wir auf die Java-API und suchen uns die Klasse Thread heraus. Am einfachsten geht das indem man die Suchfunktion des Browsers anwirft (meist STRG + F) und den Begriff sucht. Oben sehen wir schon, das die Klasse Thread von Objekt abgeleitet wurde und Runnable implementiert hat. Das heißt für uns, das wir in unserer Download-Klasse eine Methode run() implementieren müssen. Das wird uns weiter unten schon durch den einleitenden Text und das erste Codebeispiel bestätigt. Sehen wir uns die run()-Methode etwas genauer an, in dem wir zu Method Summary scrollen und die Methode run() anklicken. Alternativ kann hier wieder die Suchfunktion angeworfen werden. Hier erfahren wir, das die run()-Methode den Arbeitsprozess anwirft. Unter See also werden noch die Methoden start() und stop() aufgeführt. Schauen wir uns start() einmal genauer an. Hier kommen wichtige Dinge zum Vorschein: Die start()-Methode ruft die run()-Methode auf und erzeugt einen neuen Thread. Auch welche Exception ausgelöst wird, wenn bereits die start()-Methode aufgerufen wurde, wird gezeigt. Mit diesen Informationen können wir nun anfangen unseren Download-Thread zu programmieren.

public class DownloadThread extends Thread {
  private String url;

  DownloadThread(String u) {
    this.url = u;
  }

  public void run() {
    // Download starten
  }
}

// Irgend wo im Hauptprogramm
DownloadThread dt =
    new DownloadThread("http://www.google.de/");
dt.start();

Ein weiteres Beispiel: Wir programmieren gerade an einem BBCode-Parser in PHP und suchen die Parameter für die Funktion **preg_replace().

Eine Tolle Anlaufstelle für alle Fragen dieser Art ist die Seite GotAPI.com (Nachtrag: Leider gibt es diese Seite nicht mehr). Eine sehr zu empfehlende Seite. Sie integriert in viele APIs eine tolle Suchfunktion. Bei unserem Beispiel gehen wir auf gotapi.com und wählen auf der Hauptseite PHP aus. Als nächstes geben wir in das Suchfeld oben links preg ein und wir erhalten sofort eine Liste mit Funktionen, die zum Suchbegriff passen. Wir wählen preg_replace. In der Beschreibung sehen wir sofort, wie die Funktion anzuwenden ist und können dies in unserem Code verwenden.

$data = "[b]Nicht schlecht[/b] der Parser.";
$bbCode = array("@[b]@", "@[/b]@");
$htmlCode = array("**", "**");

$output = preg_replace($bbCode, $htmlCode, $data);

Es lohnt sich also, bei Fragen und Problemen nicht gleich Google zu befragen, sondern sich auch einmal näher mit der Dokumentation zu beschäftigen.