| Beide Seiten der vorigen RevisionVorhergehende ÜberarbeitungNächste Überarbeitung | Vorhergehende Überarbeitung |
| software_entwicklung:javadoc:start [2010-06-24 10:42] – zueger1 | software_entwicklung:javadoc:start [2010-10-13 15:15] (aktuell) – gelöscht zueger1 |
|---|
| ====== 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. | |
