Javadocs erstellen

[propra]

Hallo zusammen,

ich weiß gar nicht, ob dies ein Anfängerthema ist, aber da ich mich zu ersten Mal damit auseinander setze, habe ich es hier gepostet.
Wie der Titel es schon verrät, möchte ich nun mein Projekt mit Javadoc dokumentieren und wollte auf diesem Wege nach ein paar Tipps fragen, die ich beachten sollte.
Ich benutze Eclipse als IDE und habe auch schon gefunden, das man für einzelne Klassen oder Methoden diesen Kommentar bzw. sein Gerüst nachträglich durch erzeugen lassen kann. Da ich bisher so gesehen ohne Dokumentation gearbeitet habe, würde ich gerne wissen, ob es eine Funktion gibt, die allen Klassen und Methoden im Nachhinein einen Kommentar hinzufügt.
Des Weiteren würde mich interessieren, wie man so ein Gerüst für den Kommentar sinnvoll aufbaut.

/**
 * @author propra
 *
 */

oder

/**
 * @param args
 * 	 
*/

Bisher sehen die nämlich sehr stiefmütterlich aus, wenn Ihr wisst, was ich meine.
Gibt es irgendwo die Möglichkeit sich mal Beispiele anzusehen, wo man evtl. auch die eine oder andere Inspiration mitnehmen kann?

Vorab vielen Dank

 

[HimBromBeere]

Guck dir doch einfach einige Javadocs an (z.B. auf Java Platform SE 6). Den Inhalt kannste von denen ja übertragen. Vom Stil her: Argumente (soweit nicht klar aus der Benennung ersichtlich) sowie Funktion der Methode benennen, Autor ist auch nett zu wissen, achja, und ganz wichtig die geworfenen Exceptions.

 

[Schandro]

Da ich bisher so gesehen ohne Dokumentation gearbeitet habe, würde ich gerne wissen, ob es eine Funktion gibt, die allen Klassen und Methoden im Nachhinein einen Kommentar hinzufügt.

Lass das doch lieber weg und füg die Javadocs per Hand hinzu, dadurch siehst du immer direkt wo noch javadocs fehlen. Die automatisch generierten Gerüste wären eh relativ wertlos solange sie nicht noch per Hand beschrieben wurden.

 

[propra]

Vielen Dank für die schnellen Antworten.

Guck dir doch einfach einige Javadocs an (z.B. auf Java Platform SE 6). Den Inhalt kannste von denen ja übertragen. Vom Stil her: Argumente (soweit nicht klar aus der Benennung ersichtlich) sowie Funktion der Methode benennen, Autor ist auch nett zu wissen, achja, und ganz wichtig die geworfenen Exceptions.

Der Link zeigt mir ja leider nur das Ergebnis. Mich würde eher der Quelltext interessieren, um ein Gefühl dafür zu bekommen, wie das aussehen muss.
Dabei fällt mir aber ein, dass ich doch auch irgendwie die Quelltexte der Standardbibliothek einsehen können müsste. Dann hätte ich doch genau, was ich möchte. Weiß jemand, ob und wo das geht?

Lass das doch lieber weg und füg die Javadocs per Hand hinzu, dadurch siehst du immer direkt wo noch javadocs fehlen. Die automatisch generierten Gerüste wären eh relativ wertlos solange sie nicht noch per Hand beschrieben wurden.

Da ich bisher noch gar keine verwendet habe, war die Idee jetzt eigentlich alle auf einmal irgendwie erzeugen lassen und dann nach zu bearbeiten. So würde ich sehen, was noch kommentiert werden muss, aber so wie du es vorgeschlagen hast ja auch. Also vergessen wir das wieder schnell.

 

[HimBromBeere]

Ich hatte angenommen, du möchtest wissen, was inhaltlich da rein gehöt.
Syntaktisch gesehen ist das aber mit Eclipse stinkeeinfach. Du schreibst deine Kommentare immer fein detailiert (nur die mit /** gekennzeichneten werden von Javadoc analysiert) und dann machst du einen Projekt-Export nach Javadoc (File-->Export->Java->Javadoc)., fertig.

Automatische Kommentare nützen di herzlich wenig, da ja kein Werkzeug voraussehen kann, was du mit deinen Klassen und Methoden vorhast.

EDIT: einige Parameter für deine Kommentare kann Eclipse aber tatsächlich automatisch ergänzen. Setze dafür den Cursor direkt ÜBER eine Methoden- oder Klassendefinition und schreibe /**
Dann eine Leerzeile und Eclipse sollte dir sowas wie geworfene Exceptions, Eingangsparameter und Rückgabewert automatisch ergänzen

 

[Michael...]

Dabei fällt mir aber ein, dass ich doch auch irgendwie die Quelltexte der Standardbibliothek einsehen können müsste. Dann hätte ich doch genau, was ich möchte. Weiß jemand, ob und wo das geht?

Die Sourcen liegen dem JDK bei: src.zip

 

[Schandro]

Wenn du die Sourcen eingebunden hast kannst du einfach mit Strg+Linksklick zur jeweilligen Klasse, Methode usw. springen.

 

[propra]

Hallo zusammen,

vielen Dank für die vielen Tipps. Sourcen sind nun eingebunden und es klappt.
Ich denke, damit ist das Thema erledigt.

 

[propra]

Hallo zusammen,

in den Code Conventions von Sun steht, dass ein Beginning Comment den Klassennamen, Versionsnummer und Angaben zum Copyright beinhalten soll.
Meine Frage wäre nun, ob ich jetzt wirklich "Copyright (c) 2011-2012 propra. All Rights Reserved." schreiben soll und was das für Auswirkungen hat. Ist das so auch in Deutschland gängige Praxis?
Dann steht im Code Example:

/*
 * %W% %E% Firstname Lastname
 */

Ich verstehe nicht, was die Zeile bewirkt.
Vielen Dank

 

[maki]

"Copyright" gibt es in diesem Sinne in D nicht, und je nachdem was du für Libs verwendet hast auch nicht in anderswo

Für mich gibt es nix unwichtigeres als das @author tag, wichtig ist mir:
- Beschreibung der public Methode (WAS und nicht WIE)
- Beschreibung der Parameter, falls vorhanden
- Beschreibung des Rückgabewertes, falls vorhanden
- Beschreibung der mögl. Exceptions (!!!), falls vorhanden

Man sollte natürlich darauf achten dass die JavaDoc echte Infos hinzufügt, sonst kann sie weggelassen werden.

 

[HimBromBeere]

Naja, sofern du im Team arbeitest, solltest du schon sowas erwähnen wie author und version, damit nachvollziehbar ist, wer wann wass an der Klasse verändert hat und wie weit man evtl. zurückspulen muss, um auf einen funktionalen Stand zu kommen... (falls der neue nicht so funktioneiert wie gewollt).

 

[maki]

In einem "richtigen" Team macht das Author tag auch keinen Sinn, da jeder alles ändern darf/soll, sowas wie "privaten Code" bzw. "Code ownership" gibt es da nicht.
Das Versions tag kann schon Sinn machen bei public APIs, aber das ist nochmal ein anderes, komplexeres Thema.

Für alles andere gibt es doch das SCM, da steht schon drinnen wer wann was geändert hat.

 

[propra]

Habt vielen Dank für die Antworten.

Leider ist bisher niemand auf die Codezeile aus meinem Post eingegangen. Leider weiß ich immer noch nicht, was das bedeuten soll. ???:L

 

[HimBromBeere]

MUSS:

/**
describe what your class/ method is for and eventually under which conditions it can bes used
@param ...
@return ...
@ throws ...
*/

KANN (je nach weiteren Mitarbeitern, Vertrieb des Produktes...)

/**
@author
@version
*/

 

[propra]

/*
 * %W% %E% Firstname Lastname
 */

Sorry, das Code-Beispiel hier meinte ich.