Ich gebe mir immer Mühe die JavaDoc Kommentare sauber aufzubauen, doch jedesmal mit dem AutoFormatter zerschiesst es mir den Kommentar:
Das kann man doch sicher irgendwo ausschalten?
Vorher:
* Sucht ob das Mapping bereits gespeichert wurde
*
* @param vz
* @param bereich
* @param gang
*
* @return Resultat
*
* 0 = Nicht gefunden
* 1 = Gefunden
*/```
Nachher:
``` /**
* Sucht ob das Mapping bereits gespeichert wurde
*
* @param vz
* @param bereich
* @param gang
*
* @return Resultat
*
* 0 = Nicht gefunden 1 = Gefunden
*/```
In Eclipse in den Einstellungen unter Code Style -> Formatter die off/on tags aktivieren. dann kann man mit @formatter:off/on einzelne Bereiche kennzeichnen die der AutoFormatter ignorieren soll.
Da ich nicht mit Eclipse arbeite, kann ich es nicht genau sagen wo es geht, aber es sollte irgendwo in den Einstellungen die Möglichkeit geben, einzustellen, wie der JavaDoc formatiert werden soll.
Dabei kommt mir aber bei deiner Funktion eine Frage, warum verwendest du bei so einer Funktion nicht einen boolean? Das würde es einfacher zu lesen machen und man würde diese zusätzliche Erklärung nicht benötigen.
isMappingExists() -> true gefunden
isMappingExists() -> false nicht gefunden
[QUOTE=CyborgGamma]
Dabei kommt mir aber bei deiner Funktion eine Frage, warum verwendest du bei so einer Funktion nicht einen boolean? Das würde es einfacher zu lesen machen und man würde diese zusätzliche Erklärung nicht benötigen.
isMappingExists() -> true gefunden
isMappingExists() -> false nicht gefunden[/QUOTE]
Guter Einwand, aber die Funktion ist noch nicht fertig, es kann auch noch Fehler geben. Deshalb ein int.
etwas trivial aber könnte hilfreich genug sein es zu erwähnen:
mit einer zusätzlichen Zeile zwischen 0 = und 1 = bleibt es dauerhaft bei einzelnen Zeilen,
so wie dank der Leerzeile 9 nicht mit dem @return zusammengefasst
* Sucht ob das Mapping bereits gespeichert wurde
*
* @param vz
* @param bereich
* @param gang
*
* @return Resultat
*
* 0 = Nicht gefunden
*
* 1 = Gefunden
*/
etwas platzintensiv, aber gerade für ‘noch nicht fertig’ und seltene Sonderaufzählungen und im Vergleich zur Alternative @formatter eine schnelle kleine akzeptable Lösung
* Sucht ob das Mapping bereits gespeichert wurde
*
* @param vz
* @param bereich
* @param gang
*
* @return Resultat
*
* 0 = Nicht gefunden <br>
* 1 = Gefunden
*/```
gibts auch noch, ob mit oder ohne /, <p> ebenso, wenn auch für anderes gedacht
[java - Javadoc - Paragraph Separator - Stack Overflow](http://stackoverflow.com/questions/5260368/javadoc-paragraph-separator)
private Methoden brauchen im Regelfall gar keine JavaDoc, weil es Implementierungsdetails sind.
Javadoc ingoriert auch alle privaten Methoden per default. d.h. dafuer wiurd keine Javadoc erstellt selbst wenn Javadoc KOmmentare vorhanden sind - aus gutem Grunde IMHO
private Methoden brauchen im Regelfall gar keine JavaDoc, weil es Implementierungsdetails sind.
Javadoc ingoriert auch alle privaten Methoden per default. d.h. dafuer wiurd keine Javadoc erstellt selbst wenn Javadoc KOmmentare vorhanden sind - aus gutem Grunde IMHO[/QUOTE]
Das macht durchaus sinn ja. Vielen Dank für den Tipp. Mit den Kommentaren bin ich sowieso immer ein wenig unsicher…
*** Edit ***
Noch ein kleiner Nachtrag zu den Kommentaren:
Einfach den JavaDoc aus dem Formatter zu nehmen hilft nicht allzuviel. Weil in der Vorschau wird der text trotzdem wieder hintereinander geschrieben.
Am besten macht man tatsächlich ein . So sieht es überall schigg aus
[quote=headnut]Aber das mit dem wäre auch akzeptabel.[/quote]ich benutze für sowas richtige HTML-Listen:/** * Sucht ob das Mapping bereits gespeichert wurde * * @param vz * @param bereich * @param gang * * @return Resultat * <dl> * <dt>0</dt><dd> Nicht gefunden </dd> * <dt>1</dt><dd> Gefunden</dd> *</dl> */
mit dem passenden Templates ist das gar kein Problem.
[quote=SlaterB]bisschen arg unleserlich im Quellcode, im Editor, allzu oft kommt man ja auch direkt vorbei[/quote]Wenns danach geht macht man gar keinen Kommentar und gibt ein enum mit sprechend benannten Werten zurück.
Deswegen hatte ich ja bei so einer Funktion true und false vorgeschlagen. Wenn es mehr Zustände gibt würde ich auch das Enum bevorzugen, anstelle Integerwerte, wo niemand weiß was diese Bedeuten.
Um Ausnahmefälle bzw genauer gesagt Errors zu reagieren, kann man auch mit Exceptions arbeiten.
Wenn ich irgendwelche HTML-Bfehle im Javadoc einbaue, dann landen die rechts der 80-Zeichen-Begrenzung. Dann stören sie im Quellcode nicht den Lesefluss, im Javadoc ist aber trotzdem alles hübsch formatiert.
