Nächste Seite: Werkzeuge zur Generierung
Aufwärts: Generierung der Dokumentation
Vorherige Seite: Generierung der Dokumentation
Hierbei gibt es zwei Schulen: Die eine Seite bringt die
Referenz-Dokumentation direkt in den Quellen unter, und die
andere zieht es vor, dies in separaten Dokumenten zu verwalten.
Wichtig ist, daß die Verbindung von Quellen mit der Referenz-Dokumentation
nicht mit literate programming zu verwechseln ist,
wie Knuth es für TEX eingeführt hat, da eine Referenz-Dokumentation
nur beschreibt, wie ein Modul zu benutzen ist und nicht wie
sein Innenleben funktioniert.
Für beide Schulen gibt es gute Gründe:
Abbildung 4.4:
Referenzseite eines Java-Moduls
|
- Wenn der Programmtext und die zugehörige Referenz-Dokumentation
ein gemeinsames Dokument bilden, ist die Gefahr geringer, daß
beide nicht miteinander synchronisiert sind.
Außerdem wird damit dem Programmierer unmittelbar die
Verantwortung zur Verwaltung der Referenz-Dokumentation
übertragen.
- Andererseits sind in vielen Fällen die textuellen
Aufbereitungsmöglichkeiten innerhalb der Programme
sehr beschränkt - so ist es bei einigen Systemen nicht
möglich, Tabellen unterzubringen.
Natürlich gibt es auch hierfür Lösungen:
So ist bei einigen Oberon-Systemen die Einfügung beliebigen
formatierten Textes bishin zu Animationen möglich
(entsprechende Arbeiten gibt es z.B. von Mössenböck)
und alternativ könnten auch textbasierte Formatierungssysteme
wie z.B. TEX eingebettet werden. Allerdings ist es
nicht ganz einfach, diese Varianten ohne weiteres in HTML
zu verwandeln.
- Häufig wird die Referenz-Dokumentation modifiziert, ohne
daß der eigentliche Programmtext geändert werden muß,
z.B. um den Text didaktisch besser aufzubereiten oder
ganz schlicht Schreibfehler zu korrigieren.
Dies führt dann dazu, daß das betroffene Modul und alle davon
abhängigen Module vollkommen unnötig frisch
übersetzt werden müssen.
Nächste Seite: Werkzeuge zur Generierung
Aufwärts: Generierung der Dokumentation
Vorherige Seite: Generierung der Dokumentation
Andreas Borchert
2000-12-18