Dokumentation in Java 

Die Dokumentation einer Bibliothek ist wie ein Wörterbuch für diese Bibliothek, sie erklärt die Wörter dieser Bibliothek. Sie wird manchmal auch als „API-Spezifikation “ bezeichnet, da eine Bibliothek manchmal auch als eine “API ” bezeichnet wird.

Die Java-SE -API-Dokumentation ist eine Sammlung von Erklärungen zur Bedeutung von Namen, welche von der Standardbibliothek von Java  definiert werden. Die Java-SE -API-Dokumentation kann vom Hersteller kostenlos bezogen werden und läßt sich auch im World-Wide Web  lesen. Der Typ einer von der Standardbibliothek festgelegten Konstanten kann in der Java-SE -API-Dokumentation nachgelesen werden. Dort finden sich auch weitere Erklärungen zur Bedeutung solch einer Konstanten.

»java.lang.Integer.MAX_VALUE« [Dokumentation, überarbeitet]

java.lang
Class Integer
Field Summary
static int MAX_VALUE

Der maximale Wert des Datentyps »int«.

Wir sehen in der Dokumentation des Bezeichners »MAX_VALUE« aus der Klasse »java.lang.Integer«:

• den Namen des Pakets der Klasse: »java.lang«,
• die Art »Class« und den Namen »Integer« des Referenztyps,
• den Titel »Field Summary«, welcher die Auflistung der Felder der Klassen einleitet,
• die Spezifikation des Feldes mit der Angabe »static« (s.u.), dem Typ »int«, und dem Namen »MAX_VALUE«,
• sowie schließlich einer englischsprachigen Beschreibung (hier übersetzt) der Bedeutung dieses Feldes in einer Proportionalschrift.

(In diesem Kurs geben wir statt englischsprachiger Texten oft eine deutsche Übersetzung an.)

Der Typ eines Namens  steht in der Dokumentation direkt vor  jenem Namen.
Die Beschreibung der Bedeutung  folgt nach dem in Schreibmaschinenschrift gesetzten Teil.

Die Java-SE -API-Dokumentation, die JLS  und die tools -Dokumentationen sind die drei wichtigsten Original-Quellen zur Programmiersprache Java. Während die JLS  die eigentliche Programmiersprache beschreibt (einschließlich von – beispielsweise – Literalen, Operatoren und elementaren Typen) und die tools -Dokumentationen die verschiedenen Dienstprogramme (wie den Compiler), beschreibt die Java-SE -API-Dokumentation die Standardbibliothek der Programmiersprache.

Die Dokumentation einer Klasse  hält fest, welche Einträge die Klasse enthält. In der Dokumentation der Klasse »java.lang.Integer« findet man auch eine Erklärung des Feldes »MAX_VALUE«.

Einzelne Teile der Dokumentation

»java.lang.Integer.MAX_VALUE« [Dokumentation, überarbeitet]

java.lang
Class Integer
Field Summary
static int MAX_VALUE

Der maximale Wert des Datentyps »int«.

Wir bezeichnen hier einzelnen Teile der Dokumentation mit Begriffen, die so nicht allgemein üblich sind:

• Das Lemma  ist das, was dokumentiert wird, beispielsweise »MAX_VALUE«.
• Die Proklamation  ist ein kurzer (meist einzeiliger) Text, welcher Eigenschaften des Lemmas in einer Kurzschreibweise, wie beispielsweise »static int MAX_VALUE«, angibt. Die verwendete Kurzschreibweise ähnelt Quelltext.
• Vor der Proklamation findet sich oft ein Prolog, der – ebenfalls in einer Kurzschreibweise – einige zusätzliche Informationen gibt.
• Die Prosa  ist ein natürlichsprachiger (also beispielsweise ein deutscher oder englischer) Text, der weitere Informationen über das Lemma enthält.

Das Lemma

MAX_VALUE

Die Proklamation

static int MAX_VALUE

Die Prosa

Der maximale Wert des Datentyps »int«.

Zitat (als Beleg für das Wort „Lemma“)

“Stichwort in einem Nachschlagewerk” (Duden  zu „Lemma“)

Zitat (als Beleg für das Wort „Prosa“)

“In some situations additional rules are needed that may be expressed using either ECMAScript algorithm conventions or prose requirements.” (ECMAScript -Norm)

Zur englischen Sprache

Obwohl die Original-Spezifikation und Dokumentation von Java SE  in englisch verfaßt sind, ist es nicht  nötig, Englisch zu lernen, um Java  zu erlernen. Denn die wichtigsten Informationen aus der Spezifikation und der Dokumentation von Java  können auch in deutschsprachigen Nachschlagewerken nachgelesen werden. Beispielsweise im „Java-Programmierhandbuch“ aus dem Verlag „dpunkt “, das zum Zeitpunkt der Niederschrift dieses Satzes auch kostenlos im Web gelesen werden kann.

Modifizierer

Durch die An- oder Abwesenheit eines Modifizierers  wird dem Lemma eine Eigenschaft zu- oder abgesprochen. Solch ein Modifizierer ähnelt einem Adjektiv des Lemmas.

»static«

Bei »static« handelt es sich um ein Schaltwort, durch dessen Anwesenheit das Lemma als statisch  gekennzeichnet wird.

Ein statischer Name  ist ein Name, der ohne Objekt verwendet werden kann. Objekte werden erst im Aufbaukurs behandelt werden.

“Index ”

Unter “Index ” findet man in der Dokumentation auch ein alphabetisches Verzeichnis aller Felder.

Direktzugriff mit einer Suchmaschine

Manchmal kann mit einer Suchmaschine direkt auf eine Seite zugegriffen werden, die einen Typ oder einen Eintrag dokumentiert, indem man nach dem Namen des Typs oder Eintrags sucht. Manchmal ist es nötig, noch das Paket oder die Java -Version hinzuzufügen, wie beispielsweise »9 java.lang Integer« oder »9 java.lang pi«.

Einordnung der Dokumentation

Während die früher kurz vorgestellte Java Language Specification  wie eine Grammatik  für Java  ist, ist die hier vorgestellte Dokumentation der Standardbibliothek wie ein Wörterbuch  für Java.

Belege zur Bezeichnung von Wertnamen ⃗

Die folgenden Zitate aus der Dokumentation von 2018  zeigen, daß in der offiziellen Dokumentation tatsächlich diverse Bezeichnungen für Wertnamen verwendet werden (“variable ”, “constant ” und “field ”).

»docs.oracle.com/javase/9/docs/api/index-files/index-13.html«, 2018-01-25

MAX_VALUE - Static variable in class java.lang.Integer
        A constant holding the maximum value an int can have, 2^31-1.

»docs.oracle.com/javase/9/docs/api/java/lang/Integer.html«, 2018-01-25

Field Summary
        static int MAX_VALUE
                A constant holding the maximum value an int can have, 2^31-1.

Die Dokumentation von Paketen ⃗

Die Pakete der Bibliothek werden auf Seiten namens »package-summary.html« dokumentiert.

So finden wir die Dokumentation des Pakets zu »docs.oracle.com/javase/9/docs/api/java/lang/Integer.html« beispielsweise auf »docs.oracle.com/javase/9/docs/api/java/lang/package-summary.html«.

Diese Seite ist auch von der Seite des Typs über die Verbindung „Package“ erreichbar.

Die Reihenfolge des Lesens der Dokumentation ⃗

Wenn man sich vollständig über einen Eintrag aus einem Paket, wie beispielsweise »java.lang.Math.PI«, informieren will, dann sollte man mindestens die folgenden drei Texte in dieser Reihenfolge lesen, falls sie einem bisher noch nicht bekannt sind:

• Den Beschreibungstext in der Dokumentation des Pakets (also beispielsweise von »java.lang«). Er enthält Informationen, die für alle Teile des Paketes gemeinsam gelten. (Es ist nicht nötig, die kurzen Beschreibungen aller Typen des Paketes zu lesen.)
• Den Einführungstext ganz am Anfang der Dokumentation des Typs (also beispielsweise von »java.lang.Math«). Er enthält Informationen, die für alle Teile des Typs gemeinsam gelten. (Es ist nicht nötig, die Beschreibung der einzelnen Einträge zu lesen.) Und schließlich
• die Dokumentation des Eintrags (also beispielsweise von »java.lang.Math.PI«).

Übungsaufgaben

/   »MAX_PRIORITY«

Entnehmen Sie der Java-SE -API-Dokumentation den Typ und die Bedeutung des Namens »java.lang.Thread.MAX_PRIORITY«.

(Bei dieser Aufgabe muß die Bedeutung nicht  genau verstanden werden. Es reicht, wenn der Anfang der Prosa vorgelesen  wird.)

Aussprachehinweis

thread θrɛd

/   »SIZE«

Entnehmen Sie der Java-SE -API-Dokumentation den Typ und die Bedeutung des Namens »java.lang.Integer.SIZE«.

(Bei dieser Aufgabe muß die Bedeutung nicht  genau verstanden werden. Es reicht, wenn der Anfang der Prosa vorgelesen  wird.)

Aussprachehinweis

size  sɑɪz

Ausgabe von »javac« *

Der Java -Compiler kann, wenn er mit der Option »-Xprint« aufgerufen wird, eine Auflistung der Einträge eines Referenztyps aus der Standardbibliothek ausgeben, beispielsweise mit »javac -Xprint java.lang.Integer« oder »javac -Xprint Main.java«. So können Kurzbeschreibungen eines Typs auch ohne Zugang zur Dokumentation betrachtet werden.