# Javadoc: @value tag nicht für private fields?



## -frank (8. Okt 2007)

ich habe in einem konstruktor einen comment à la "Setzt den wert von ABC auf {@value ABC_DEFAULT_VALUE}.".
das funktioniert leider nur, wenn das static final field ABC_DEFAULT_VALUE public ist. ansonsten wird das referenzierte feld von javadoc nicht gefunden.
1. ist das immer so oder habe ich etwas falls konfigurierte bzw. kann ich javadoc so konfigurieren, dass es doch geht?
2. falls dies immer so ist: warum? (ich meine, klar, da der wert static final ist, muss man das feld nicht durch "private" acccess schützen. Allerdings scheint ein public field immer in der javadoc doku auf und lenkt somit vielleicht unnötigerweise Aufmerksamkeit auf sich.)


----------



## maki (8. Okt 2007)

> 1. ist das immer so oder habe ich etwas falls konfigurierte bzw. kann ich javadoc so konfigurieren, dass es doch geht?


der Parameter heisst -private


----------



## -frank (9. Okt 2007)

maki hat gesagt.:
			
		

> > 1. ist das immer so oder habe ich etwas falls konfigurierte bzw. kann ich javadoc so konfigurieren, dass es doch geht?
> 
> 
> der Parameter heisst -private



ja, danke, ich sehe gerade, dass ich den parameter unabsichtlich entfernt hatte. aber mein prinzipielles problem löst es nicht. ich habe es irreführend beschrieben: was ich gerne hätte, wäre, private methoden und felder NICHT in der doku zu haben aber trotzdem @value verweise auf private static final fields machen zu können. IMO würde das durchaus sinn machen. aber das wird dann wohl nicht gehen oder? (so schlimm ists nicht...)


----------



## maki (9. Okt 2007)

> was ich gerne hätte, wäre, private methoden und felder NICHT in der doku zu haben aber trotzdem @value verweise auf private static final fields machen zu können.


Naja, das widerspricht sich, findest du nicht auch? 

Entweder du zeigst die private fields an, oder nicht.


----------



## -frank (9. Okt 2007)

maki hat gesagt.:
			
		

> Naja, das widerspricht sich, findest du nicht auch?



naja, wieso? man soll ja nicht die private fields sehen, sondern nur in der dokumentation einer nicht-private methode den wert einer private konstante anzeigen können. wenn dies nicht geht, muss ich entweder ein feld public machen, das eigentlich private sein sollte (--> nur aufgrund der Doku die implementierung ändern), oder aber ich habe unnötige redundanzen in der doku: zb steht in der doku eines konstruktors "der wert für die maximale anzahl von elementen wird auf 10 gesetzt". die 10 steht eigentlich in einer konstante. ändert man nun die konstante und vergisst auf die Doku änderung, ist die Doku falsch...


----------



## tuxedo (9. Okt 2007)

Wenn ich irgendwo private Variablen habe, dann hab ich in der Library in der sie auftauchen, eh keinen direkten Zugriff. Ergo interessiert's mich als benutzer der Library nicht. Und folglich wäre es etwas unnötig, wenn nicht sogar verwirrend wenn in der ApiDoc private Variablen stehen die ich so gar nicht nutzen kann...

Aber ich verstehe deinen Standpunkt.. Aber ist es denn wirklich nötig den Benutzer über die Doc über den Wert einer private-variablen zu informieren? Hast du's mal mit protected versucht?


- Alex


----------



## -frank (9. Okt 2007)

naja, es sieht bei mir in etwa so aus:


```
public SomeClass {

    private static final int DEFAULT_VALUE = 123;
    private int value;

    public SomeClass(int value) {
        this.value = value;
    }

    /**
     * ...
     * Setzt value auf {@value #DEFAULT_VALUE}.
     */
    public SomeClass() {
        this.value = DEFAULT_VALUE;
    }

    /**
     * ...
     * Setzt value auf {@value #DEFAULT_VALUE} falls nicht spezifiziert in den properties.
     */
    public SomeClass(Properties props) {
        if (props.getProperty("value") != null) {
            ..
        } else {
            this.value = DEFAULT_VALUE;
        }
    }
}
```

keine frage, es ist kein großes problem, wenn ich DEFAULT_VALUE public mache, aber ich finde es nicht so unsinnig, was ich tue. (oder?)
protected habe ich noch nicht getestet, aber ich nehme an, dass man einfach immer nur auf felder verweisen kann, die dem javadoc-level entsprechen. also wenn man nur public und default anzeigen lässt, wird man wohl auch nur die werte von public und default feldern anzeigen können (was ja bei @see und @link IMO auch absolut sinn macht, aber bei @value ? ...)


----------



## tuxedo (10. Okt 2007)

Hmm, wenn die Variable eh final ist, warum wäre es dann "tragisch" wenn sie public wäre? Wieso dürfen andere Klassen nicht den Default-Wert wissen?

- Alex


----------



## -frank (10. Okt 2007)

alex0801 hat gesagt.:
			
		

> Hmm, wenn die Variable eh final ist, warum wäre es dann "tragisch" wenn sie public wäre? Wieso dürfen andere Klassen nicht den Default-Wert wissen?



tragisch nicht, aber naja, ein beispiel: der defaultwert wird jetzt absolut angegeben als "123". später ändere ich die implementierung, entferne die konstante und berechne den wert stattdessen anders (zb gibts dann eine DEFAULT_PERCENTAGE und über die komme ich zu meiner default value). bei einer public konstante muss ich nun aber aufpassen, dass auf diese konstante keine anderen klassen zugreifen.

wie gesagt "tragisch" ist es nicht, weil ich in meinem speziellen fall nicht vorhabe die konstante in nächster zeit zu entfernen (also ich hab sie halt jetzt public gemacht). trotzdem: ich musste nur für die dokumentation etwas an der implementierung ändern. das scheint mir falsch.


----------



## maki (10. Okt 2007)

> trotzdem: ich musste nur für die dokumentation etwas an der implementierung ändern. das scheint mir falsch.


Der Fehler ist folgender: Du willst in der API doc keine privaten Felder haben, aber dann möchtest du wieder den Wert eines privaten Feldes in der API doc verwenden... das ist der Widerspruch 

javadoc ist recht grob in den Einstellungen, entweder du hast die Informationen über private Felder, oder nicht.
Dazwischen gibt's nix.


----------



## tuxedo (10. Okt 2007)

Naja, ich würde hier in dem Fall in der Doku nicht auf die Variable zugreifen. Schon gar nicht wenn in aussicht steht dass sich da in nicht allzuferner zukunft was ändert. 

Wenn ich eine Lib schreibe die einen Algorithmus benutzt und ich in der JavaDoc Doku den Algorithmus beschreibe, dann muss ich so oder so, wenn sich der Algo ändert, die Doku nochmal anfassen.

Find ich jetzt für meinen Teil nicht so tragisch. Auch würde ich meine IMplementierung nicht der Doku deswegen anpassen...Eher umgekehrt.

- Alex


----------



## -frank (10. Okt 2007)

als wirklichen widerspruch sehe ich es nicht, denn es wäre ja nur ne zusätzliche info in der doku. "der default wert ist 123 (kann sich aber in späteren versionen ändern)". so ne information kann IMO in der doku recht nützlich sein und ist IMO unabhängig von der visibility der doku. dass der default wert 123 ist, ist auch für den user interessant, der nur die public doku hat. er muss aber nicht wissen, wie das private field heißt bzw. wie ich überhaupt zu dem default wert komme. einfache lösung ist natürlich einfach den wert in der doku entsprechend anzupassen, aber wenn ich zb 4 konstruktoren habe, muss ich den wert 5 mal ändern (1x die konstante selbst und 4x die doku). und da vergisst man dann schnell mal eine änderung, schon ist ein fehler drin.

ich schätze, dass es eher mit der javadoc implementierung zu tun hat, dass es nicht geht, als dass es wirklich bewusst so entschieden wurde. aber naja, tragisch ist es wie gesagt nicht. ich werde es in zukunft so machen, dass ich von fall zu fall entscheide. entweder die konstante wird public gemacht und ich zeige in der doku ihren wert an oder ich verlinke auf die konstante (und wenn der visibility level stimmt, kann man sich ja dann den wert ansehen) oder aber ich machs eben ganz anders.

danke auf jeden fall an euch!


----------

