JavaDoc Minimal mit Standard-Doclet

Warum

javadoc generiert Code-Dokumentation aus speziellen Kommentaren in Java-Quellcode.
Default-Output ist HTML. Mit entsprechenden "doclets" können aber alle möglichen Ausgabeformate geschrieben werden, bis hin zu Präprozessorfunktionalität.
Das Programm javadoc ist in Suns JDKs enthalten (/bin).

Benutzt javac und ist wahrscheinlich deshalb so kreuzlangsam ;)

Basisaufruf

javadoc <packagename> [-sourcepath <pfadzudensourcen>]
javadoc <sourcefile1> <sourcefile2> ...

Vorgehen

Mehrzeiliger Kommentar, beginnend mit "/**" statt "/*" im Quellcode vor dem zu dokumentierenden Element: eben ein "Doc-Kommentar", gesetzt direkt vor Klasse / Interface / Methode / Felddefinition, auf die Bezug genommen wird.

Kann bei Verwendung des Standard-Doclets HTML enthalten, sinnvoll: <code>...</code> um Schlüsselwörter und Namen.
Zusätzlich angereichert durch spezielle Schlüsselwörter im Format @name (javadoc-("Tags").

Beispiel

/**
 * Das ist um mal zu sehen wie gut <blink>javadoc</blink> funktioniert.
 *
 * @author Simon Staiger
 * @version 0.1
 * @see package.Otherclass
 */
...Klassendefinition...

Wichtigste javadoc-Tags

Jeweils "@" gefolgt von Tagname und eventuell Inhalt(en)

@author
@version
@param
Parametername, dann Beschreibung
@return
@exception
Klassenname gefolgt von Beschreibung
@throws
@see
Eintrag taucht in "See also"-Sektion auf.
Drei Spielarten:
1. Plaintext: @see "Java-Dokumentation" - Bücher etc.
2. HTML: @see <a href="http://sstaiger.de">Simons Site</a> - Online-Ressourcen
3. Feature/Label: @see ExampleB.TempUnit TempUnit
  Label muss nicht angegeben werden. Feature kann sein:
  - pkgname[.classname]
  - classname[#methodname[(paramtypes*)]]
  - methodname[(paramtypes)]
  - [classname]#fieldname
{@link reference}
Spezielles Schlüsselwort, darf überall auftauchen. Wie @see, taucht aber im Fließtext auf.

Packages und Projekte

Für diese Higher-Level können gesonderte HTML-Dateien package.html (Im Verzeichnis) und overview.html (im Root-Dir der Sourcen) angelegt werden. Diese Dokumente können ebenfalls die javadoc-Schlüsselwörter wie @see etc. enthalten.

Lesen der generierten Dokumente

Siehe help-doc.html in generierter Dokumentation :-)

Links und Referenzen

How to Write Doc Comments for the Javadoc Tool
javadoc - The Java API Documentation Generator (Dokumentation)
Nur Aufruf + Kurzbeschreibung Tool:
Java in a Nutshell 4th ed p251ff
Konventionen und Spezial-Kommentarliste für javadoc:
Java in a Nutshell 4th ed chap7 p222
Javadoc 1.4.2 Tool:
Übersicht mit Links zu APIs für eigene Doclets