15 Dokumentation
15.1 Wozu Dokumentationen?
 
Die Java-Klasse Math. Ein Blick in die Java-Dokumentation (z.B. über JavaEditor -> Hilfe -> API) zeigt für die Java-Klasse eine Fülle von Informationen. Mit einer Reihe von diesen Informationen können wir im Moment noch nichts anfangen. Was aber schon jetzt verständlich ist, ist die Aufzählung der in der Klasse Math implementierten Methoden . Wir erkennen die Signatur (Parameterliste) und die Rückgabewerte. Die Auflistung zeigt dem Nutzer dieser Klasse, welche Methoden zur Verfügung stehen und wie man sie gebrauchen kann.
  Damit sind wir auch schon der Beantwortung der Frage, wozu Dokumentationen sinnvoll sind, sehr nahe.
Wieder- verwendung und Dokumentation Die Klasse Mathematik war so angelegt, dass sie mitsamt ihren Klassenmethoden an vielen Stellen wieder verwendet werden kann. So kann man z.B. den Bytecode der Klasse Mathematik an einen "Kunden" weitergeben und dabei lediglich mitteilen, welche Methoden die Klasse besitzt und wie diese benutzt werden. Genauer bedeutet dies, dass man dem Kunden sagt, welche Parameter der Aufruf der einzelnen Methode (angegeben durch seinen Typ) verlangt und von welchem Typ ein eventuell zurückgegebener Wert ist. Ferner interessiert noch die Funktionalität der Methode, der Kunde muss also erfahren können, was die Methoden leistet. Wir sagen der Kunde muss die Signatur der Klasse kennen, um sie in seinen Programmen verwenden zu können. Den Kunden hat also der Quelltext der Klasse Mathematik nicht zu interessieren, aber er benötigt eine Dokumentation.
Mit  javadoc.exe stellt j2sdkxxx von SUN(TM) ein komfortables Werkzeug zur Erstellung einer Benutzer-Dokumentation zur Verfügung. Es lässt sich aus einer selbstgeschriebenen Klasse eine Dokumentation erstellen, die der der Klasse Math in Aussehen und Informationsgehalt bis aufs Haar gleicht. Im Javaeditor ist diese Dokumentationserstellung und -nutzung hervorragend integriert.  Wir lernen hier, wie man Dokumentationen mit geringem Aufwand erstellt und auch verwendet?
   
zu 15.2 Dokumentationskommentare im Java-Quelltext
zur Startseite www.pohlig.de  (C) MPohlig 2003