Javadoc in Java

Dokumentiere eine Methode mit einem besonderen Kommentar, damit Leser und Werkzeuge sehen, was sie nimmt und was sie zurueckgibt. In Yard.java schreibe eine Methode add, die int x und int y nimmt und ihre Summe zurueckgibt. Setze einen /** */-Block direkt ueber add. Schreibe darin einen kurzen Satz zur Arbeit, dann markiere jeden Parameter mit @param und das Ergebnis mit @return. In main drucke add(10, 2). Kompiliere mit javac Yard.java und starte java Yard. Der Bildschirm soll 12 zeigen. Lass Namensregeln fuer die naechste Seite — diese Lektion ist die Form des Dokumentationskommentars, nicht die Wahl von Namen.

/** ueber die Methode setzen

Die Debugging-Seite druckte Werte, um eine falsche Summe zu finden. Diese Seite schreibt einen Dokumentationskommentar ueber eine saubere Methode. Oeffne Yard.java. Halte den oeffentlichen Klassennamen Yard. Loesche uebrige println-Debug-Labels, wenn sie die Dokumentationsgeschichte begraben, uebrige equals / ==-Demos, uebrige Machine-horn-Dateien und jeden Tastatur-Scanner. Das Programm darf nicht auf Tippen warten. Fuer diese Demo brauchst du keine Importzeile.
In Yard behalte eine kleine Methode und ein kurzes main. Der Dokumentationsblock muss unmittelbar ueber der Methode sitzen, die er beschreibt. Eine Leerzeile zwischen schliessendem */ und der Methodenzeile ist in Ordnung. Verstecke den Block nicht in main. Setze den Block nicht unter den Methodenkoerper.
Schreibe den Kommentarbeginn mit zwei Sternen nach dem Schraegstrich:
/**
Dann schreibe einen klaren Satz, was add tut. Dann schreibe die Tags. Schliesse mit:
*/
Die Methode selbst bleibt gewoehnliches Java:
static int add(int x, int y) {
return x + y;
}
Javadoc aendert nicht, wie return arbeitet. Es sagt einem Leser, was die Methode verspricht, bevor er jede Zeile des Koerpers liest.

Aus dem Ordner, der Yard.java haelt, starte javac Yard.java. Wenn Klammern, geschweifte Klammern und Semikolons passen, schreibt javac keine eigene Zeile. Dann starte java Yard — nicht java Yard.java. Lass die Endung .java beim Startbefehl weg. Halte eine oeffentliche Klasse in der Datei, damit der Name zu Yard passt.
Der Bildschirm zeigt 12. Geh den Lauf einmal durch. Java startet bei Yard.main. Der Aufruf add(10, 2) betritt die Methode mit x gleich zehn und y gleich zwei. Die return-Zeile gibt zwoelf zurueck. System.out.println schreibt diese Zahl. Der Javadoc-Block druckt nicht von allein. Der Block ist fuer Leser und Dokumentationswerkzeuge. Der Anfaengerbeweis auf dieser Seite bleibt ein korrekter Lauf nach einem klaren Kommentar.
Lies den Kommentarblock, waehrend du die Methodensignatur anschaust. Der Satz Adds two numbers. passt zur Arbeit von return x + y;. Die Zeile @param x first number benennt den ersten Parameter. Die Zeile @param y second number benennt den zweiten Parameter. Die Zeile @return the sum of x and y benennt das Ergebnis. Halte die Tag-Schreibweise genau: @param und @return nutzen das @-Zeichen und lateinische Buchstaben.
Wenn du noch x=10 und y=2 und dann 8 aus einer Debugging-Datei siehst, wechsle zur Javadoc-Lehrdatei und starte java Yard erneut. Wenn du nur // Adds two numbers. ueber die Methode schreibst, hast du einen gewoehnlichen Zeilenkommentar geschrieben, keinen Javadoc-Block. Behalte die Doppelstern-Form /**, damit der Block Dokumentation ist und keine einzeilige Notiz.
Sag die Regel laut, waehrend du den Bildschirm beobachtest: dokumentiere ueber der Methode, markiere die Parameter, markiere den Rueckgabewert, dann kompiliere und starte, um zu beweisen, dass die Methode noch funktioniert. Erfinde auf dieser Seite keine langen Naming-Vortraege. Naming wartet auf die naechste Lektion.

Die Tag-Karte lesen

Eine kurze Tabelle haelt die drei Stuecke, die du in den Kommentar getippt hast. Das oeffnende /** */ markiert einen Dokumentationsblock. @param beschreibt einen Parameternamen. @return beschreibt den Wert, den die Methode zurueckgibt. Behalte den Methodennamen add und den Aufruf add(10, 2), damit der Bildschirm eine einzige klare Zahl bleibt.
Die Tabelle ist die kurze Landkarte dieser Seite. Zuerst setzt du den Block. Dann markierst du Eingaben und Ausgabe. Dann pruefst du mit javac und java Yard. Rate nicht, dass jeder Kommentarstil Javadoc sei. Loesche den Block nicht, bevor du weisst, dass das Programm noch 12 druckt.

Halte die Tabelle neben der Lehrdatei, waehrend du editierst. Zeige auf @param x in der Datei, dann auf int x in der Signatur. Zeige auf @param y, dann auf int y. Zeige auf @return, dann auf die return-Zeile. Dieses Zuordnungsspiel ist die ganze Anfaengeridee in einem Durchgang. Werkzeuge, die Javadoc lesen, suchen nach diesen Tags. Menschliche Leser nutzen dieselbe Karte, wenn der Methodenkoerper spaeter waechst.
Wenn uebrige Debugging-Demos noch in der Naehe liegen, behalte sie als Geschichte. Fuer diese Lektion starte die Javadoc-Lehrdatei, damit der Bildschirm 12 aus add zeigt, nicht gelabelte x=-Zeilen aus einer Jagd. Wenn javac ueber doppelte oeffentliche Klassen klagt, halte nur Yard public.

Gewoehnliches // ist kein Javadoc

Eine Zeile, die mit // beginnt, ist eine Notiz fuer jemanden, der die Datei liest. Sie ist nuetzlich, und dieser Kurs hat Zeilenkommentare schon frueher genutzt. Sie ist nicht die Dokumentationsblock-Form, die diese Seite lehrt. Javadoc fuer eine Methode beginnt mit /** und endet mit */. Die Tags @param und @return sitzen in diesem Block.
Wenn du einen einfachen String unter die Methode nach anderen Anweisungen setzt, ist dieser String keine Methodendokumentation. Der Dokumentationsblock muss der Kommentar sein, der oben an der Methode haengt. Halte den Block eng an add. Halte main frei von falschem Dokumentations-Theater. Der Aufruf in main bleibt ein normaler Druck der zurueckgegebenen Summe.
Wenn der Kommentar falsch ist, der Methodenkoerper aber richtig, kann javac trotzdem gelingen und java Yard trotzdem 12 drucken. Deshalb verlangt diese Seite, Kommentar und Signatur zusammen zu lesen, nicht nur den Bildschirm. Der Bildschirm beweist die Mathematik. Der Kommentar beweist, dass du den Vertrag beschriftet hast.

Verglichen mit Debugging-Drucken

Auf der Debugging-Seite antwortete println, was deine Zahlen wirklich waren, wenn eine Summe falsch wirkte. Auf dieser Seite antwortet Javadoc, was add verspricht, bevor ein Leser in den Koerper eintaucht. Du kompilierst weiterhin Yard.java und startest java Yard. Die neuen Tokens sind /**, @param und @return ueber einer Methode.
Debugging nutzte gewoehnliche Ausgabe als Taschenlampe. Javadoc nutzt einen strukturierten Kommentar als Schild an der Methodentuer. Wenn das Schild zu Parametern und Rueckgabe passt, raten Leser weniger. Wenn das Schild fehlt, kann das Programm trotzdem laufen — die Dokumentationsgewohnheit fehlt trotzdem.
Wenn eine uebrige Debugging-Datei noch offen ist, siehst du vielleicht x=10, y=2 und eine alte Summe. Wechsle zur Javadoc-Datei, damit main add(10, 2) druckt und die Methode den Dokumentationsblock traegt. Halte Naming-Stil-Vortraege von dieser Seite fern. Halte Tastatureingabe von dieser Seite fern.

Vor dem Naming

Du kannst /** */ ueber add setzen, @param x, @param y und @return markieren und nach java Yard trotzdem 12 sehen. Kompiliere Yard.java und starte java Yard fuer die behaltene Demo. Der Kommentar sagte Lesern den Vertrag. Die naechste Seite ist Naming, wo du klare Namen fuer das waehlst, was du schreibst.
Behalte die dokumentierte add-Demo fuer ein klares Kommentar-plus-Lauf-Paar. Halte Debugging-Dateien von dieser Seite fern, wenn du Dokumentation uebst. Halte Naming-Dateien von dieser Seite fern, bis zu jener Lektion. Diese drei Gewohnheiten sind der Checkpoint, bevor du weitergehst. Wenn die Tags zur Signatur passen und der Bildschirm 12 zeigt, hat Javadoc fuer diese Lektion seine Arbeit getan und du bist bereit fuer das naechste Thema ueber Naming.
Ein letzter Gang durch den Ordner: ein oeffentliches Yard, ein dokumentiertes add, ein Druck in main, kein Tastaturwarten, keine erzwungenen Naming-Regeln. Starte javac Yard.java und java Yard noch einmal auf der Demo, die du offen haeltst. Wenn der Bildschirm noch 12 zeigt und der Kommentar noch ueber add mit @param und @return sitzt, ist die Dokumentationsform solid und der Kurs kann auf der naechsten Seite zu Naming wechseln. Bevorzuge einen klaren Dokumentationsblock an einer Methode, damit jeder Lesevorgang dieselbe Karte lehrt.