====== JavaDoc ======
JavaDoc ist ein Software-Dokumentationswerkzeug, welches das automatische Erstellen von HTML-Dokumentationsseiten ermöglicht. Es wurde von Sun Microsystems entwickelt und ist Bestandteil des Java Developer Kits.

===== Funktionsweise =====
JavaDoc parst den Java-Quellcode und generiert daraus automatisch HTML-Dokumente. Dazu sind jedoch spezielle JavaDoc-Kommentare notwendig (beginnend mit ''%%/**%%''). Die Position dieser Kommentare gibt wie gewohnt an zu was der Kommentar gehört: immer zum nachfolgenden Block. Im Kommentar können spezielle JavaDoc-Tags verwendet werden.

===== JavaDoc-Tags =====
^ Tag & Parameter                          ^ Beschreibung  ^ Verwendbar in  ^
| ''@author //name//''                     | Beschreibt den Autor | Klasse, Interface |
| ''@version //version//''                 | Erzeugt einen Versionseintrag. Darf max. einmal pro Klasse oder Interface verwendet werden! | Klasse, Interface |
| ''@see //reference//''                   | Erzeugt einen Link auf ein anderes Element der Dokumentation. | Klasse, Interface, Instanzvariable, Methode |
| ''@param //name description//''          | Parameterbeschreibung einer Methode | Methode |
| ''@return //description//''              | Beschreibung des Rückgabewertes einer Methode | Methode |
| ''@deprecated //description//''          | Beschreibt eine veraltete Methode, die nicht mehr verwendet werden sollte. Sollte immer mit der @Deprecated-Annotation verwendet werden! | Methode |
| ''@exception //classname description//'' | Beschreibung einer Exception, die von dieser Methode geworfen werden kann. | Methode |
| ''@throws //classname description//''    | ::: | ::: |
| ''@since //jdk-version//''               | Seit wann die Funktionalität existiert. | Klasse, Interface, Instanzvariable, Method |
| ''{@inheritDoc}''                        | Kopiert die Beschreibung aus der überschriebenen Methode. | Überschreibende Methode |
| ''{@link reference}''                    | Link zu einem anderen Symbol. | Klasse, Interface, Instanzvariable, Methode |
| ''{@linkPlain reference}''               | Link zu einem anderen Symbol. Der Link wird jedoch als Standardtext angezeigt. | Klasse, Interface, Instanzvariable, Methode |
| ''{@value}''                             | Gibt den Wert eines konstanten Feldes zurück. | Statisches Feld |
| ''{@code}''                              | Formatiert Text buchstabengetreu mit dem Quelltextzeichensatz und unterdrückt die Interpretierung von beinhalteten HTML oder Javadoc-Tags. | Klasse, Interface, Instanzvariable, Methode |
| ''{@literal}''                           | Kennzeichnet buchstabengetreuen Text und unterdrückt die Interpretierung von beinhalteten HTML oder Javadoc-Tags. | Klasse, Interface, Instanzvariable, Methode |


===== Beispiele =====

==== Hello-World-Beispiel ====
<code java>
/**
 * Ein einfaches Hello-World-Beispiel in Java
 * mit Javadoc-Kommentaren. Wieviel Text in
 * so einem Kommentar steht, ist egal.
 *
 * @author Martin Züger
 * @version 0.1
 */
public class HelloWorld {

    /** 
     * Hauptmethode: Wird beim Starten aufgerufen
     *
     * @param args Kommandozeilenparameter
     */
    public static void main(String[] args) {
        System.out.println("Hello NTB!");
    }
}
</code>

===== Dokumentation generieren =====
Die Dokumentation kann mithilfe des Kommandozeilentools ''javadoc'' erstellt werden. Dieses verfügt über eine relativ grosse Anzahl [[.:Parameter|möglicher Parameter]].

Die einfachste Art die Dokumentation zu erstellen ist, ''javadoc'' von Hand ohne Parameter aufzurufen:
  javadoc PACKAGE
Damit wird vom Paket PACKAGE (welches im aktuellen Verzeichnis liegen muss) eine Dokumentation erstellt und ebenfalls im aktuellen Verzeichnis abgelegt.

Praktischer ist es jedoch, wenn man das Verzeichnis für die Java-Quellen und das Ausgabeverzeichnis angeben kann. Zudem ist es mühsam, wenn immer alle Pakete einzeln angegeben werden müssen. Abhilfe schaffen die beiden Parameter ''-d'' und ''-sourcepath'' sowie eine Datei mit einer Liste aller Pakete, für die eine Dokumentation benötigt wird. Dies sieht dann folgendermassen aus:
  javadoc -sourcepath /java/jdk/src/share/classes -d /java/jdk/build/api @packagelist
Dabei muss im aktuellen Verzeichnis eine Datei mit dem Namen ''packagelist'' existieren, die alle gewünschten Pakete (durch Zeilenumbrüche getrennt) beinhaltet.

TODO Einfügen: Javadoc mit Ant und Make erstellen!

===== Links =====
  * [[http://www.oracle.com/technetwork/java/javase/documentation/javadoc-137458.html| JavaDoc bei Oracle]]