Was rein sollte: Das Verhalten. Wenn ein Wert irgendwelchen Beschränkungen unterliegt, dann sollte dokumentiert werden, was die Methode damit macht.
Wenn z.B. ein Wert auf min und max korrigiert wird, dann sollte das im Setter stehen. Im Getter sollte entsprechend im Return-Bereich Zahlenbereich des Wertes angegeben werden.
Kurz: Der Benutzer dieser Methoden sollte sie nicht erst ausprobieren müssen, um zu sehen, was passiert.
Persönliche Vorgehensweise (und wirklich, es ist genau das): Was ich mir angewöhnt habe, ist, bei Get/Set Paaren für Attribute den Header der Methoden beider Methoden gleich zu lassen. Also kein "Sets the ..." und "Returns the ..." sondern einfach nur die Beschreibung des Attributs. Das irgendwas gesetzt oder returned wird, schreib ich dann in die entsprechenden @param oder
@Return
Dokumentation im Code finde ich grundsätzlich nicht schlecht, vor allem bei komplexen längeren Algorithmen mit vielen Abhängigkeiten. Es ist eine Sache zu erkennen, WAS da gemacht wird, das WARUM ist zwei Jahre später aber oft viel wichtiger. Man kann natürlich auch den gesamten Algorithmus im Javadoc dokumentieren.
Wenn ich so was habe, mach ich meistens beides. Bevor ich eine Methode schreibe, wird zuerst mal im JAvadoc die Doku geschrieben, was sie machen soll. Das "wie" wird zumindest teilweise hinzugefügt, Referenzen (@see) auf andere bereits existierende public Methoden. Diese Doku wird dann in die einzelnen Punkte zerlegt, in die Methode geschrieben. Dann wird entschieden, was davon in Methoden auszulagern wäre und was nicht. Dann wird jeder einzelne Punkt umgesetzt. Die Beschreibung bleibt im oft im Code stehen, auch wenn eine Methode mit lesbarem Namen aufgerufen wird, damit man beim Lesen des Codes der Beschreibung im Header folgen kann.
Da ich oft mehrere Jahre nach Implementierung nochmal ran muss und für bestimmte Kunden Änderungen vornehmen soll, steht auch dabei, warum ich bestimmte Umsetzungsentscheidungen getroffen habe, manchmal auch, welches Ticket für den entsprechenden Block verantwortlich ist, worauf achtzugeben ist (denn sonst gibt's in Folge ein Bugticket eines anderen Kunden, der das genau so haben wollte, was ich grad geändert hab).
Doku und Entwicklung gehen Hand in Hand. In früheren Zeiten (assembler) war es nicht unüblich, jede einzelne Zeile zu dokumentieren und sei sie noch so eindeutig.