JavaDocは中々優れたツールなんだけど
皆あんまり真面目に書かないんだよな

事前条件の提示とかフェイルファストとかスレッドセーフとか
確かにSunのドキュメントは細かく書かれてて戸惑いが少ない。
驚き最小限の法則に基づけばこの姿勢は大切。