Java Reference
In-Depth Information
6.4.1■Automatische Dokumentation des Quelltextes und
Dokumentationskommentare
Die Dokumentation von Quelltext ist für die Fehlervermeidung (gerade von logischen Feh-
lern) wichtig, denn man denkt bei der Dokumentation noch einmal über den Quellcode
nach. Vor allen Dingen aber wird die Wartbarkeit verbessert, wenn man selbst oder ein
anderer Programmierer später noch einmal den Quellcode anfassen muss.
Es gibt nun in JavaScript eine Spezialversion eines mehrzeiligen Kommentars, der zu auto-
matischen Dokumentationszwecken verwendet werden kann. Dabei wird der mehrzeilige
Kommentar einfach mit
/**
begonnen (also zwei Sternchen). Aus Sicht von JavaScript ist
das dann nur ein gewöhnlicher mehrzeiliger Kommentar. Aber es gibt Dokumentationstools,
die dies als
Token
verstehen und nachfolgenden Kommentar verarbeiten können, um eine
Dokumentation zu erstellen. Beachten Sie, dass diese Kommentare immer
unmittelbar vor
der Struktur zu notieren sind, die damit kommentiert werden sollen.
Das Verfahren ist von Java motiviert, wo schon seit Beginn ein Tool namens
javadoc
die
automatisiere Dokumentation aus dem Quelltext heraus gestattet. Denn auch wenn es Laien
oder Anfänger eher für nebensächlich halten - Dokumentieren des eigenen Quellcodes ist
extrem wichtig und wenn das ohne großen Aufwand für einen Programmierer möglich ist,
wird der sich dieser - ot eher als lästig empfundenen - Plicht nicht entziehen. Mit geeig-
neten Tools wie
YUIDoc
(
http://yui.github.io/yuidoc/
),
jsdoc
bzw.
jsdoc3
(
https://github.com/
jsdoc3/jsdoc
)
oder
jGrouse Doc
(
https://code.google.com/p/jgrousedoc/
) geht das Erzeugen
von Kommentaren mittlerweile auch in JavaScript automatisiert.
Im Grunde arbeiten die Tools alle ähnlich. Ein Programm, das mit diesen speziellen Kom-
mentaren umgehen kann, erzeugt auf der Basis dieser Kommentare innerhalb einer Java-
Script-Quelldatei oder eines entsprechenden JavaScript-Bereichs in einer Webseite eine
Anzahl HTML-Dateien als API-Dokumentation der dokumentierten Strukturen. Vereinfacht
ausgedrückt schreibt so ein Tool die innerhalb der Datei in speziellen Kommentaren einge-
schlossenen Texte in eine HTML-Datei. Darin können sich beliebige Informationen beinden.
Innerhalb des Kommentarcontainers
/** ... */
beindet sich wie gesagt der Kommentar-
text, der neben reinem Text spezielle Steuerbefehle beinhalten kann, die automatisiert zur
Erstellung bestimmter Standardelemente in der Dokumentation verwendet werden. Die
meisten Tools verwenden weitgehend analoge Token. Sie werden dort innerhalb des Kom-
mentarcontainers mit dem speziellen Zeichen
@
eingeleitet und sollten immer in einer ein-
zelnen Zeile innerhalb des Containers stehen. Für Details muss man sich die Dokumentation
eines konkreten Tools ansehen, denn die tatsächlich von einem konkreten Tool genau unter-
stützten Token unterscheiden sich und einige der speziellen Steueranweisungen werden nur
dann verwendet, wenn dem entsprechenden Tool beim Aufruf zugehörige Optionen überge-
ben werden oder gewisse Voraussetzungen gegeben sind. Die nachfolgende Tabelle 6.2 ent-
hält eine kleine Auswahl wichtiger Token, die in den drei genannten Tools alle verfügbar
sind:
Search WWH ::
Custom Search