Wie Verwenden von JavaDoc Ihre Klassen zu Dokument
Ein Schritt bleibt, bevor Sie öffentlich mit Ihrem heißen neuen Klassenbibliothek oder Anwendung gehen kann: die Dokumentation für die Klassen vorbereitet. Glücklicherweise bietet Java ein Tool namens JavaDoc
das kann automatisch ausgefallene HTML-basierte Dokumentation erstellen basierend auf Kommentare in Ihren Quelldateien.Alles, was Sie tun müssen, ist einen Kommentar für jede öffentliche Klasse, Feld hinzufügen und Methoden- dann die Quelldateien durch die laufen javadoc Befehl- voil # 225-! Sie haben professionell aussehende, Web-basierte Dokumentation für Ihre Klassen.
Hinzufügen JavaDoc Kommentare
Die Grundregel JavaDoc Kommentare zu schaffen, ist, dass sie beginnen mit / ** und enden mit * /. Sie können JavaDoc Kommentare in jeder der drei verschiedenen Orten in einer Quelldatei platzieren:
Unmittelbar vor der Erklärung einer öffentlichen Klasse
Unmittelbar vor der Erklärung eines öffentlichen Bereich
Unmittelbar vor der Deklaration einer öffentlichen Methode oder Konstruktor
Ein JavaDoc Kommentar kann Text enthalten, der die Klasse, ein Feld oder Methode beschreibt. Jede nachfolgende Zeile einer mehrzeiligen JavaDoc Kommentar beginnt in der Regel mit einem Stern. JavaDoc ignoriert diesen Stern und alle Leerzeichen zwischen ihm und dem ersten Wort auf der Linie.
Der Text in einem Javadoc-Kommentar kann HTML-Markup enthalten, wenn Sie Lust auf Formatierung angewendet werden soll. Sie sollten mit Überschriften-Tags (und so weiter) zu vermeiden, weil JavaDoc diejenigen schafft, und Ihre Position Tags nur die Dinge verwirren. Aber Sie können Tags für Fettdruck verwenden und kursiv (und) oder Format Codebeispiele (verwenden Sie den Tag).
Darüber hinaus können Sie spezielle umfassen doc-Tags vorsehen, dass bestimmte Informationen, die von JavaDoc verwendet, um die Seiten der Dokumentation zu formatieren.
| Etikett | Erläuterung |
|---|---|
| @Autor | Liefert Informationen über den Autor, in der Regel theAuthor Name, E-Mail-Adresse, Website-Informationen, und zwar bald. |
| @Version | Zeigt die Versionsnummer an. |
| @schon seit | Verwendet, um die Version anzuzeigen, mit der dieser Klasse, Feld, ormethod hinzugefügt wurde. |
| @param | Gibt den Namen und die Beschreibung eines Verfahrens orconstructor. |
| @Rückkehr | Bietet eine Beschreibung eines Rückgabewert der Methode. |
| @throws | Gibt Ausnahmen, die durch ein Verfahren orconstructor geworfen werden. |
| @deprecated | Zeigt an, dass die Klasse, ein Feld oder Methode ist veraltet andshouldn't verwendet werden. |
Um Ihnen eine Vorstellung davon, wie JavaDoc Kommentare typischerweise verwendet werden, diesen Code zu sehen.
Beachten Sie, dass für die Mitarbeiter Klasse zu kompilieren, müssen Sie auch eine Klasse bieten benannt Adresse, was eine Straßenadresse. Die folgende einfache Klasse genügen:
public class Adresse implementiert klonbar {public String street-public String city-public String state-public String zipCode-}Diese Codes zeigt einen Mitarbeiter-Klasse mit JavaDoc Kommentare.
Paket com.lowewriter.payroll - / ** Stellt ein Mitarbeiter * @author Doug Lowe * @author LoweWriter.com * @version 1.5 * @since 1.0 * / public class Employee {private String nachName-private String vorName-private Doppel Gehalt. - / ** stellt die Adresse des Mitarbeiters * / public Adresse Adresse -.. / ** Erzeugt einen Mitarbeiter mit dem angegebenen Namen * @param Nachnamen, um den Nachnamen des Mitarbeiters * @param Vorname der Vorname des Mitarbeiters * / public Employee (String.. nachName, String vorName) {this.lastName = nachName-this.firstName = vorName-this.address = new Adresse () -} / ** Ruft den Nachnamen des Mitarbeiters * Ein String @return repräsentiert die letzte des Mitarbeiters * Name *.. / public String getLastName () {this.lastName zurückkehren -} / ** den Nachnamen des Mitarbeiters Sets * @param Ein String Name VZ des Mitarbeiters * Nachname enthält * / public void setLastName (String nachName) {this.lastName = nachName.. -..} / ** den Vornamen des Mitarbeiters Ruft * @return Eine Zeichenfolge mit der ersten * Namen des Mitarbeiters darstellt * / public String getFirstName () {this.firstName zurückkehren -} / ** den Vornamen des Mitarbeiters Sets * @param vorName. Ein String mit der Vorname * Mitarbeiters enthält * / public void setFirstName (String vorName) {this.firstName = vorName -}... / ** das Gehalt des Mitarbeiters erhält * Eine doppelte @return das Gehalt des Mitarbeiters darstellt * / public double getSalary ( ) {this.salary zurückkehren -} / ** das Gehalt des Mitarbeiters Sets * @param nachName Ein Doppel der * Gehalt des Mitarbeiters enthält * / public void setSalary (doppeltes Gehalt) {this.salary = Gehalts-}}..Mit dem Befehl javadoc
Das javadoc Befehl hat ein paar Dutzend Optionen, die Sie festlegen können, ist es ein komplizierter Befehl machen zu verwenden. Sie können jedoch alle diese Optionen ignorieren einen Basissatz von Seiten der Dokumentation zu erstellen. Geben Sie einfach den vollständigen Pfad für alle Java-Dateien, die Sie für die Dokumentation erstellt werden soll, wie folgt aus:
javadoc com lowewriter Abrechnung *. java
Das javadoc Befehl erstellt die Dokumentationsseiten im aktuellen Verzeichnis, so können Sie in das Verzeichnis wechseln möchten, wo Sie die Seiten wollen zunächst zu wohnen.
Für genauere Informationen über diesen Befehl verwenden, lesen Sie die javadoc-Dokumentation auf der Sun-Website.
Anzeigen von JavaDoc Seiten
Nachdem Sie den javadoc Befehl ausführen, können Sie die Dokumentationsseiten zugreifen, indem Sie mit der index.html-Seite zu starten. Um schnell diese Seite anzuzeigen, geben Sie einfach index.html an der Eingabeaufforderung, nachdem Sie den javadoc Befehl ausführen. Oder Sie können Ihren Browser, navigieren Sie zu dem Verzeichnis zu starten, wo Sie die Dokumentation Seiten erstellt, und öffnen Sie die Seite index.html.
Wenn Sie denken, diese Seite vertraut aussieht, ist das, weil die Dokumentation für die Java-API erstellt wurde JavaDocs. So sollten Sie bereits wissen, wie Sie Ihren Weg zu finden, um diese Seiten.
Um für eine Klasse in der Dokumentation suchen, klicken Sie auf den Link des Klassennamen. Eine Seite mit einer vollständigen Dokumentation für die Klasse kommt. JavaDocs erzeugt diese Seite aus der Quelldatei.
