、CoreAPIであっても、自分たちが組んだクラスであっても、オブジェクト同士が協調して動くという点では同列なわけで、適度に中身が隠蔽されるのなら、その中身をさらけ出す説明ではなくて、協調動作の中でなぜこういう動作をするのか、なぜこいつだけが外に見えているのか、このオブジェクトにメッセージを送るとオブジェクトにどんな変化がおきるのか、といった情報は、やはり書いておくべきだと思う。
JavadocはXPでいう最低限のドキュメントに当たると思う。
Eclipseを使えば、自作のクラスであってもJavadocを見ながらコーディングができるわけで役割が大きい。
つまり、Javadocでは外部から見る仕様、コーディングのために必要な情報を全て、簡潔に書く必要があるということでしょう。