javadoc für getter und setter

[Chris Seidel]

Hallo NG,

gibt es einen Weg, nur das unter einem getter/setter liegende Feld zu
dokumentieren, in der javadoc dann aber am getter/setter den Kommentar zu
sehen?


Danke

[Stefan Ram]

Post by Chris Seidel
gibt es einen Weg, nur das unter einem getter/setter liegende
Feld zu dokumentieren, in der javadoc dann aber am
getter/setter den Kommentar zu sehen?

Einen Code-Generator?
(Am einfachsten zu realisieren mit einem Vorverarbeiter.)

[Chris Seidel]

Post by Stefan Ram
Einen Code-Generator?

Ja klar aber welcher? Eclipse macht das nicht. Ein Plugin?

Post by Stefan Ram
(Am einfachsten zu realisieren mit einem Vorverarbeiter.)

Hä?

[Stefan Ram]

Post by Stefan Ram
(Am einfachsten zu realisieren mit einem Vorverarbeiter.)

(...)

http://google.to/search?q=Vorverarbeiter

Beispielsweise

http://www.nothingisreal.com/gpp/

Ich erzeuge damit auch Dokumentationskommentare. Eines
meiner Makros lautet beispielsweise:

(Es folgen jetzt überlange Zeilen.)

$define SEE
@version VERSION
@since SINCE
@see <a href="http://www.purl.org/stefan_ram/java/$1.java">source code</a>
@see <a href="http://www.purl.org/stefan_ram/html/ram.jar/$1.html">documentation</a>
@see <a href="http://www.purl.org/stefan_ram/pub/ram-jar">Library homepage</a>

»VERSION«, »SINCE« und »$1« werden darin dann durch andere Makros
bzw. das Argument ersetzt und das Ergebnis ist dann beispielsweise:

@version ***@2006-05-01T00:52:46+02:00
@since 2006-01-24T23:38:54+01:00
@see <a href="http://www.purl.org/stefan_ram/java/de/dclj/ram/type/pair/ComparableLocatablePair0.java">source code</a>
@see <a href="http://www.purl.org/stefan_ram/html/ram.jar/de/dclj/ram/type/pair/ComparableLocatablePair0.html">documentation</a>
@see <a href="http://www.purl.org/stefan_ram/pub/ram-jar">Library homepage</a> */

[Hauke Ingmar]

Moin!

Post by Stefan Ram

Post by Stefan Ram
(Am einfachsten zu realisieren mit einem Vorverarbeiter.)

(...)

http://google.to/search?q=Vorverarbeiter

Das Suchresultat würde mich sehr nachdenklich stimmen.

Bis denn

[Ralf Ullrich]

Post by Chris Seidel
Hallo NG,
gibt es einen Weg, nur das unter einem getter/setter liegende Feld zu
dokumentieren, in der javadoc dann aber am getter/setter den Kommentar zu
sehen?

Ja es gibt einen Weg: Schreibe eigene Doclets, die das machen. Siehe auch:

http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/index.html

cu

[Chris Seidel]

Post by Ralf Ullrich
http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/index.html

Hm, gibts da keine fertigen?

[Ralf Ullrich]

Post by Chris Seidel

Post by Ralf Ullrich
http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/index.html

Hm, gibts da keine fertigen?

Jede Menge, einfach mal googeln oder hier:

http://java.sun.com/j2se/javadoc/faq/index.html#doclets

Aber AFAIK keinen der das macht, was du willst.


Um das zu erreichen was du willst, wäre es wohl am einfachsten den
Source-Code des Standard-Doclets herzunehmen und mit ein paar Zeilen
Anpassung dürft das, was du vorhast, schon erledigt sein.

Da der Standard-Doclet-Code aber unter der gleichen Lizenz steht, wie der
Rest des JDK-Source-Codes, darf man eigene Änderungen nicht
weiterverbreiten. Daher wirst du auch kaum ein fertiges Doclet im Netz
finden, das solche minimalen Änderungen zum Standard enthält.

cu

[Chris Seidel]

Post by Ralf Ullrich
Aber AFAIK keinen der das macht, was du willst.

Bin ich echt der erste der diesen Wunsch hat? Wie macht ihr das denn? Immer
nur den getter oder den Setter dokumentieren?

[Ralf Ullrich]

Post by Chris Seidel

Post by Ralf Ullrich
Aber AFAIK keinen der das macht, was du willst.

Bin ich echt der erste der diesen Wunsch hat? Wie macht ihr das denn?
Immer nur den getter oder den Setter dokumentieren?

1. Ist eher selten, dass ich "echte" Setter und Getter schreibe, das
versuche ich nämlich zu vermeiden.

2. Wenn es denn sein muss, dann dokumentiere ich alle drei (Getter, Setter
und Field), obwohl das Field dann private ist und nur in meiner internen
JavaDoc auftaucht.

3. Natürlich gilt 2. nur, wenn ich überhaupt dokumentiere.

cu

[Chris Seidel]

Post by Ralf Ullrich
2. Wenn es denn sein muss, dann dokumentiere ich alle drei (Getter,
Setter und Field), obwohl das Field dann private ist und nur in
meiner internen JavaDoc auftaucht.

Und schreibst dann 3 x dasselbe hin???

[Ralf Ullrich]

Post by Chris Seidel

Post by Ralf Ullrich
2. Wenn es denn sein muss, dann dokumentiere ich alle drei (Getter,
Setter und Field), obwohl das Field dann private ist und nur in
meiner internen JavaDoc auftaucht.

Und schreibst dann 3 x dasselbe hin???

U.U. bis auf die Verben, ja.

cu

[Sönke Müller-Lund]

Post by Chris Seidel
Bin ich echt der erste der diesen Wunsch hat? Wie macht ihr das denn? Immer
nur den getter oder den Setter dokumentieren?

Wozu will man getter und setter dokumentieren?

Sönke

[Christoph Maria Dahlen]

Post by Chris Seidel

Post by Ralf Ullrich
Aber AFAIK keinen der das macht, was du willst.

Bin ich echt der erste der diesen Wunsch hat? Wie macht ihr das denn? Immer
nur den getter oder den Setter dokumentieren?

In der Regel schreibe ich das Feld hin und drücke dann die
Tastenkombination meiner IDE, mit der getter/setter incl. Dokumentation
erzeugt werden.

Gruß,

Christoph

[Sebastian Stein]

Post by Chris Seidel
gibt es einen Weg, nur das unter einem getter/setter liegende Feld zu
dokumentieren, in der javadoc dann aber am getter/setter den Kommentar zu
sehen?

Ich füge in die Beschreibung des getter/setter im folgendes Konstrukt ein:

/** @see #theAttribute */

Das funktioniert, der Leser wird schon begreifen, dass er auf den Link klicken
soll.

Sebastian

[Stefan Matthias Aust]

Post by Sebastian Stein

Post by Chris Seidel
gibt es einen Weg, nur das unter einem getter/setter liegende Feld zu
dokumentieren, in der javadoc dann aber am getter/setter den Kommentar zu
sehen?

Das funktioniert, der Leser wird schon begreifen, dass er auf den Link klicken
soll.

Dokumentiert man in JavaDoc üblicherweise nicht nur die public und
protected-Methoden und sind Exemplarvariablen nicht üblicherweise
private? Ich sehe in diesem Kontext nicht, wieso es sinnvoll sein soll,
private Details zu dokumentieren, nicht aber die Schnittstelle - also
die öffentlichen getter und setter.

[Sebastian Stein]

Post by Stefan Matthias Aust

Post by Sebastian Stein
Das funktioniert, der Leser wird schon begreifen, dass er auf den Link klicken
soll.

Dokumentiert man in JavaDoc üblicherweise nicht nur die public und
protected-Methoden und sind Exemplarvariablen nicht üblicherweise
private? Ich sehe in diesem Kontext nicht, wieso es sinnvoll sein soll,
private Details zu dokumentieren, nicht aber die Schnittstelle - also
die öffentlichen getter und setter.

Naja, das ist eigentlich so ziemlich egal. Du kannst ja auch die beiden
getter/setter dokumentieren, nur musst du dann sichern, dass die Beschreibung
konsistent bleibt. Warum also nicht die Dokumentation an einer Stelle und
entsprechend darauf verweisen? Das eine ist die Theorie, das andere ist die
Praxis.

Sebastian

[Bernd Eckenfels]

Post by Sebastian Stein
Naja, das ist eigentlich so ziemlich egal. Du kannst ja auch die beiden
getter/setter dokumentieren, nur musst du dann sichern, dass die Beschreibung
konsistent bleibt. Warum also nicht die Dokumentation an einer Stelle und
entsprechend darauf verweisen? Das eine ist die Theorie, das andere ist die
Praxis.

Weil du dann auf ein Attribut verweist das Privat ist, und somit garnicht in
der JavaDoc auftaucht.

Gruss
Bernd