JavaDoc: Unterschied zwischen den Versionen

Aus Byte-Welt Wiki
Zur Navigation springenZur Suche springen
K (→‎Kommentar-Tags)
K (→‎JavaDoc-Werkzeug)
 
(27 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
 +
=JavaDoc=
 
JavaDoc ist ein kleines Werkzeug aus dem [[JDK]], mit dem sich aus speziellen Kommentaren im [[Quellcode]] eines Java-Programmes Dokumentationstexte im [[HTML]]-Format generieren lassen.<br>
 
JavaDoc ist ein kleines Werkzeug aus dem [[JDK]], mit dem sich aus speziellen Kommentaren im [[Quellcode]] eines Java-Programmes Dokumentationstexte im [[HTML]]-Format generieren lassen.<br>
 +
Dabei werden die Kommentar-Tags direkt über der zu beschreibenden Klasse notiert.<br>
 +
Innerhalb der JavaDoc-Kommentare können HTML-Tags zur Formatierung der späteren Ausgabe eingefügt werden.
 +
 +
==Was sollte dokumentiert werden?==
 +
Die Beschreibung von [[Variable|Variablen]], [[Methode|Methoden]], [[Klasse|Klassen]] und [[Package|Packages]] sollte nicht aus einer Funktionsbeschreibung bestehen, sondern vielmehr aus der Beschreibung des Einsatzzweckes oder der Wirkung des dokumentierten Codes.<br>
 +
Außerdem aus einer Beschreibung von erwarteten [[Argument|Argumenten]] und Rückgabewerten und wie sich der Code verhält, wenn ungültige Werte übergeben wurden, einschließlich der Fehlerbehandlung.<br>
 +
Für schwer zu erklärende Sachverhalten können auch Code-Beispiele im Kommentar hinterlegt werden.
  
 
=Kommentar-Tags=
 
=Kommentar-Tags=
−
 
+
*'''/**''' - leitet einen JavaDoc-Kommentar ein.
−
*@value - dokumentiert ein an eine Methode übergebenes Argument. (hier am Bsp. einer Variable ''value'')
+
*'''*/''' - beendet einen JavaDoc-Kommentar.
−
*@return - dokumentier den Rückgabewert einer Methode.
+
*'''@param''' - dokumentiert ein an eine [[Methode]] übergebenes Argument.
−
*@see - dient zum Verweisen (Link) auf einen weiterführenden Text in einer (anderen) Dokumentation (Bsp.: @see javax.swing.JButton#setText() )
+
*'''@return''' - dokumentiert den Rückgabewert einer Methode.
−
*@since - dient zur Hervorhebung der Einführung in den Code, also seit wann (z.B. Versionsnummer) ein bestimmtes Feature verfügbar ist.  
+
*'''@see''' - dient zum Verweisen (Link) auf einen weiterführenden Text in einer (anderen) Dokumentation (Bsp.: @see javax.swing.JButton#setText() )
−
*@deprecated - dient zum Kennzeichnen veralteter Methode, die nicht mehr eingesetzt werden sollten.
+
*'''@since''' - dient zur Hervorhebung der Einführung in den Code, also seit wann (z.B. Versionsnummer) ein bestimmtes Feature verfügbar ist.  
−
*<code></code> - dient zum Formatieren von Code-Beispielen innerhalb der JavaDoc. (Bsp.: <code>BeispielCode bc = new BeispielCode();</code> )
+
*'''@deprecated''' - dient zum Kennzeichnen veralteter Methode, die nicht mehr eingesetzt werden sollten. Siehe auch: [[deprecated]].
 +
*'''@throws''' - dient zur Angabe von checked (geprüften) [[Exception|Exceptions]].
 +
*'''@author''' - dient zur Angabe des Autors einer [[Klasse]] oder Methode.
 +
*'''@version''' - dient zur Angabe der Version einer Klasse oder Methode.
 +
*'''@link''' - dient zur Angabe eines Hyperlinks zu einer Klasse im Kommentartext. (siehe @see)
 +
*'''<nowiki><code></nowiki>''' - dient zum Formatieren von Code-Beispielen innerhalb der JavaDoc. (Bsp.: <code>BeispielCode bc = new BeispielCode();</code>)
  
 
=Beispiel=
 
=Beispiel=
 
Ein kleines Beispiel soll die Dokumentation einer [[Methode]] verdeutlichen:
 
Ein kleines Beispiel soll die Dokumentation einer [[Methode]] verdeutlichen:
−
<code=java>/**
+
<syntaxhighlight lang="java">/**
−
  * Gibt das Ergebnis der Addition, der im übergebenen int-Array enthaltenen Zahlen zurück.
+
  * Gibt ein Image-Objekt zurück, das auf den Bildschirm gezeichnet werden kann.
−
  * @intArr ein Array mit Zahlen im primitiven Datentyp int.
+
* Das URL-Argument muss einen absoluten {@link URL} spezifizieren.
−
  * @return Ergebnis der Addition.
+
* Das Argument <code>name</code> spezifiziert dabei den relativen Teil zu der URL.
 +
* <p>
 +
* Die Methode kehrt sofort zurück, unabhängig davon, ob das Image existiert.
 +
* Wenn dieses Applet das Zeichnen auf den Bildschirm anstößt, werden die
 +
* Daten geladen.
 +
* </p>
 +
* @param  url  eine absolute URL, die den Basis-Speicherort des Bildes angibt.
 +
  * @param  name der Dateiname als Speicherort des Bildes, relativ zur URL
 +
  * @return     das Bild an der spezifizierten URL
 +
* @see        Image
 
  */
 
  */
−
public int addition(int[] intArr) {
+
public Image getImage(URL url, String name) {
−
  int x = 0;
+
    try {
 +
        return getImage(new URL(url, name));
 +
    }
 +
    catch (MalformedURLException e) {
 +
        return null;
 +
    }
 +
}</syntaxhighlight>
  
−
  for(int i = 0; i < intArr.length; i++) {
+
=JavaDoc-Werkzeug=
−
      x += intArr[i];
+
Die Erzeugung der Dokumentation aus den JavaDoc-Kommentaren kann nun mit folgendem Befehl in der Kommandozeile des Betriebssystems ausgelöst werden:<br>
−
  }
+
<code>javadoc Klassenname.java</code>
 +
Dabei erzeugt JavaDoc entsprechend der im Quelltext hinterlegten Dokumentation Webseiten mit dem Dokumentationsinhalt samt Navigation und Links.<br>
 +
Das prominenteste Beispiel für eine mit JavaDoc erzeugte Code-Dokumentation ist die [[API Dokumentation (Java)]].
  
−
  return x;
+
=Links=
−
}</code=java>
+
*[[API Dokumentation (Java)]]
−
Die Erzeugung der Dokumentation aus den JavaDoc-Kommentaren kann nun mit folgendem Befehl in der Kommandozeile des Betriebssystems ausgelöst werden:<br>
 
−
<code>javadoc Klassenname.java</code>
 
  
−
[[Kategorie:Java]]
 
 
[[Kategorie:Java Grundlagen]]
 
[[Kategorie:Java Grundlagen]]
 +
[[Kategorie:Tutorials (Java)]]

Aktuelle Version vom 5. Juli 2020, 16:15 Uhr

JavaDoc

JavaDoc ist ein kleines Werkzeug aus dem JDK, mit dem sich aus speziellen Kommentaren im Quellcode eines Java-Programmes Dokumentationstexte im HTML-Format generieren lassen.
Dabei werden die Kommentar-Tags direkt über der zu beschreibenden Klasse notiert.
Innerhalb der JavaDoc-Kommentare können HTML-Tags zur Formatierung der späteren Ausgabe eingefügt werden.

Was sollte dokumentiert werden?

Die Beschreibung von Variablen, Methoden, Klassen und Packages sollte nicht aus einer Funktionsbeschreibung bestehen, sondern vielmehr aus der Beschreibung des Einsatzzweckes oder der Wirkung des dokumentierten Codes.
Außerdem aus einer Beschreibung von erwarteten Argumenten und Rückgabewerten und wie sich der Code verhält, wenn ungültige Werte übergeben wurden, einschließlich der Fehlerbehandlung.
Für schwer zu erklärende Sachverhalten können auch Code-Beispiele im Kommentar hinterlegt werden.

Kommentar-Tags

  • /** - leitet einen JavaDoc-Kommentar ein.
  • */ - beendet einen JavaDoc-Kommentar.
  • @param - dokumentiert ein an eine Methode übergebenes Argument.
  • @return - dokumentiert den Rückgabewert einer Methode.
  • @see - dient zum Verweisen (Link) auf einen weiterführenden Text in einer (anderen) Dokumentation (Bsp.: @see javax.swing.JButton#setText() )
  • @since - dient zur Hervorhebung der Einführung in den Code, also seit wann (z.B. Versionsnummer) ein bestimmtes Feature verfügbar ist.
  • @deprecated - dient zum Kennzeichnen veralteter Methode, die nicht mehr eingesetzt werden sollten. Siehe auch: deprecated.
  • @throws - dient zur Angabe von checked (geprüften) Exceptions.
  • @author - dient zur Angabe des Autors einer Klasse oder Methode.
  • @version - dient zur Angabe der Version einer Klasse oder Methode.
  • @link - dient zur Angabe eines Hyperlinks zu einer Klasse im Kommentartext. (siehe @see)
  • <code> - dient zum Formatieren von Code-Beispielen innerhalb der JavaDoc. (Bsp.: BeispielCode bc = new BeispielCode();)

Beispiel

Ein kleines Beispiel soll die Dokumentation einer Methode verdeutlichen: 

/**
 * Gibt ein Image-Objekt zurück, das auf den Bildschirm gezeichnet werden kann. 
 * Das URL-Argument muss einen absoluten {@link URL} spezifizieren. 
 * Das Argument <code>name</code> spezifiziert dabei den relativen Teil zu der URL. 
 * <p>
 * Die Methode kehrt sofort zurück, unabhängig davon, ob das Image existiert. 
 * Wenn dieses Applet das Zeichnen auf den Bildschirm anstößt, werden die
 * Daten geladen.
 * </p>
 * @param  url  eine absolute URL, die den Basis-Speicherort des Bildes angibt.
 * @param  name der Dateiname als Speicherort des Bildes, relativ zur URL
 * @return      das Bild an der spezifizierten URL
 * @see         Image
 */
 public Image getImage(URL url, String name) {
    try {
        return getImage(new URL(url, name));
    } 
    catch (MalformedURLException e) {
        return null;
    }
 }

JavaDoc-Werkzeug

Die Erzeugung der Dokumentation aus den JavaDoc-Kommentaren kann nun mit folgendem Befehl in der Kommandozeile des Betriebssystems ausgelöst werden:

javadoc Klassenname.java

Dabei erzeugt JavaDoc entsprechend der im Quelltext hinterlegten Dokumentation Webseiten mit dem Dokumentationsinhalt samt Navigation und Links.
Das prominenteste Beispiel für eine mit JavaDoc erzeugte Code-Dokumentation ist die API Dokumentation (Java).

Links

Abgerufen von „https://wiki.byte-welt.net/mediawiki/index.php?title=JavaDoc&oldid=9236“