Share
Diese kurze Lektion behandelt Javadoc, ein hilfreiches Werkzeug zum Generieren von Dokumentation aus Ihren Java-Quelldateien. Diese Lektion ist Teil einer laufenden Reihe von Tutorials für Entwickler, die Java lernen, um Android-Anwendungen zu entwickeln.
Javadoc ist ein mit dem Java SDK bereitgestelltes Dienstprogramm, mit dem Entwickler Codedokumentationen aus Java-Quelldateien generieren können. Entwicklungsumgebungen wie Eclipse bieten integrierte Unterstützung für Javadoc und können durchsuchbare HTML-Referenzmaterialien aus Kommentaren im Javadoc-Stil generieren. Tatsächlich ist die Referenz zum Android SDK eine Form der Javadoc-Dokumentation.
Die Javadoc-Dokumentation verwendet eine Kombination aus Verarbeitung des Quellcodes (und Untersuchen von Typen, Parametern usw.) und Lesen spezieller Kommentartags, die der Entwickler als Metadaten bereitstellt, die einem Codeabschnitt zugeordnet sind.
Ein Kommentar im Javadoc-Stil muss unmittelbar vor dem damit verknüpften Code stehen. Ein Javadoc-Kommentar für eine Klasse sollte beispielsweise direkt über der Klassendeklaration und ein Kommentar für eine Methode direkt über der Methodendeklaration stehen. Jeder Kommentar sollte mit einer kurzen Beschreibung beginnen, gefolgt von einer Option mit einer längeren Beschreibung. Dann können Sie eine Reihe verschiedener Metadaten-Tags einschließen, die in einer bestimmten Reihenfolge bereitgestellt werden müssen. Einige wichtige Tags sind:
Sie können auch Ihre eigenen benutzerdefinierten Tags zur Verwendung in der Dokumentation erstellen.
Während Sie Code in Eclipse schreiben, können Sie einen Javadoc-Stil-Kommentar generieren, indem Sie das Element auswählen, das Sie kommentieren möchten (Klassenname, Methodenname usw.) und Alt-Shift-J (Cmd-Shift-J auf a) drücken Mac). Dadurch wird ein grundlegender Javadoc-Kommentar erstellt, in den Sie die Details eingeben können.
Schauen wir uns ein Beispiel an. Hier ist ein einfacher Javadoc-Kommentar, der eine Klasse beschreibt:
/ ** * Aktivität zum Laden von Layoutressourcen * * Diese Aktivität wird verwendet, um verschiedene Layoutressourcen für ein Lernprogramm zum Design der Benutzeroberfläche anzuzeigen. * * @author LED * @version 2010.1105 * @since 1.0 * / public class LayoutActivity erweitert die Aktivität
So wird es aussehen, wenn Sie die Javadoc-Dokumentation generieren:
Schauen wir uns ein Beispiel an. Hier ist ein einfacher Javadoc-Kommentar, der ein Feld innerhalb einer Klasse beschreibt:
/ ** * Debug Tag zur Verwendung der Protokollierung der Debug-Ausgabe in LogCat * / private static final String DEBUG_TAG = "MyActivityDebugTag";
So wird es aussehen, wenn Sie die Javadoc-Dokumentation generieren:
Lassen Sie uns nun zwei Beispiele für Methodenkommentare betrachten. Hier ist ein einfacher Javadoc-Kommentar, der eine Methode innerhalb einer Klasse beschreibt:
/ ** * Methode, die zwei Ganzzahlen addiert * * @param a Die erste hinzuzufügende Ganzzahl * @param b Die zweite Ganzzahl, die hinzugefügt wird * @return Die resultierende Summe von a und b * / public int addIntegers (int a, int b ) return (a + b);
Schauen wir uns nun eine Methode an, die void zurückgibt, aber eine Ausnahme auslöst:
/ ** * Diese Methode löst einfach eine Exception aus, wenn der ankommende Parameter a keine positive Zahl ist, nur zum Spaß. * * @param a Gibt an, ob eine Ausnahme ausgelöst werden soll oder nicht.
So wird es aussehen, wenn Sie die Javadoc-Dokumentation für diese beiden Methoden generieren:
Um eine Javadoc-Codedokumentation in Eclipse zu erstellen, wählen Sie im Menü Projekt die Option "Javadoc erstellen ...". Dadurch wird ein Assistent gestartet, mit dem Sie die Projekte auswählen können, für die Dokumentation erstellt werden soll.
Von diesem Assistenten aus sollten Sie Eclipse auf das entsprechende Befehlszeilentool "javadoc.exe" verweisen (Sie finden es im JDK-Verzeichnis / bin). Sie können auch einige Dokumentationseinstellungen konfigurieren, z. B. ob Sie den gesamten Code oder nur sichtbare Klassen, Member usw. dokumentieren. Wählen Sie schließlich ein Ziel für Ihre Dokumentationsdateien.
Auch ohne die Javadoc-Dateien zu generieren, zeigt Eclipse die Dokumentation im Javadoc-Stil an, wenn Sie mit der Maus über Ihre Methoden und ähnliches fahren (siehe folgende Abbildung).
Weitere Informationen finden Sie in der Javadoc-Referenz auf der Oracle-Website. Es gibt auch hilfreiche Javadoc-FAQs.
In dieser kurzen Lektion haben Sie Javadoc kennen gelernt, ein mächtiges Werkzeug, mit dem Java-Entwickler Quellcode für Referenz- und Wartungszwecke gründlich dokumentieren. Eclipse, die von vielen Android-Entwicklern verwendete Entwicklungsumgebung, bietet integrierte Unterstützung für Javadoc.
Die mobilen Entwickler Lauren Darcey und Shane Conder haben mehrere Bücher zur Android-Entwicklung mitgeschrieben: ein ausführliches Programmierbuch mit dem Titel Android Wireless-Anwendungsentwicklung und Sams TeachYourself Entwicklung von Android-Anwendungen in 24 Stunden. Wenn sie nicht schreiben, verbringen sie ihre Zeit damit, mobile Software in ihrem Unternehmen zu entwickeln und Beratungsdienste anzubieten. Sie können sie per E-Mail an [email protected], über ihren Blog unter androidbook.blogspot.com und über Twitter @androidwireless erreichen.
Accentsconagua