Ein Framework zur Erzeugung von Dokumentationen für Softwareschnittstellen


Christian Wohlfahrtstätter

Die Schnittstelle eines Softwarebausteins (z.B. einer Klasse) besteht aus allen exportierten Datenfeldern und Methoden des Bausteins sowie aus deren Spezifikation. Während sich die Syntax der Schnittstelle aus dem Quellcode extrahieren läßt, muß die Spezifikation vom Programmierer angegeben werden. In Java hat es sich eingebürgert, die Spezifikation in Form spezieller Dokumentationskommentare in den Quellcode zu schreiben und ein Werkzeug zu benutzen, das diese Kommentare extrahiert und zu einer Schnittstellendokumentation verarbeitet.

Javadoc ist ein Werkzeug von Sun Micrsosystems, welches eine Schnittstellendokumentation nach dem oben beschriebenen Verfahren generiert [Sun2001a]. In der aktuellen Version von Javadoc lässt sich die Schnittstellendokumentation in verschiedenen Ausgabeformaten erzeugen (z.B. HTML, XML, PS, PDF etc.). Das Werkzeug hat jedoch einen großen Nachteil: Die Dokumentation kann nur aus dem Quellcode einer ganz bestimmten Programmiersprache, nämlich Java, generiert werden.

Ziel dieser Diplomarbeit ist ein erweiterbares Framework zu implementierien, welches erlaubt, Schnittstellendokumentation aus dem Quellcode beliebiger Programmiersprachen zu generieren. Dabei sind folgende Bedingungen zu beachten:

  • Das Werkzeug soll in die kommerzielle Entwicklungsumgebung SNiFF+ integriert werden. Dabei werden die bereits von SNiFF+ zur Verfügung gestellten Daten (z.B. Symboltabelle) verwendet und verarbeitet.
  • Es ist ein Prototyp zu implementieren, welcher Schnittstellendokumentation für die Programmiersprache C++ in HTML-Format generiert. Für Java-Quellcode soll Javadoc transparent für den Benutzer im Hintergrund ausgeführt werden.
  • Die zu verarbeitenden Dokumentationskommentare sollen kompatibel zu den Dokumentationsrichtlinien von Sun's "Java Platform API Specification" [Sun2001b] sein.
  • Es soll eine geeignete Benutzerschnittstelle entwickelt werden, welche das Einstellen von Optionen und das Starten des Dokumentationsvorganges ermöglicht. Hierbei soll die Benutzerschnittstelle in einen allgemeinen, sprachunabhängigen Teil und in mehrere sprachspezifische Teile gegliedert werden.
  • Die Implementierung des Werkzeuges soll plattformunabhängig und portabel sein.
  • Es sollen Schnittstellen entwickelt werden, welche die Erweiterung auf zusätzliche Programmiersprachen und verschiedene Ausgabeformate ermöglichen.

[Sun2001a] http://java.sun.com/j2se/javadoc/index.html

[Sun2001b] http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Betreuer: Prof. Dr. H. Mössenböck

Ausgabe: 1. März 2001