I'm not sure if there is precedent for adding such release notes inline
in the javadoc (and subsequently removed in the next major release), but
I am not opposed to it in principle. I guess it may look something like:
* <p>Note: In this release, this constructor no longer declares
* that it throws {@code SocketException}. Callers that explicitly
* handle {@code SocketException} ( or one of its superclasses )
* may need to remove this explicit exception handling.
Anyone every encounter this kind of comment before, or have a strong
opinion either way ( I'm personally on the fence ).
-Chris.
On 06/08/2013 20:25, Matthew Hall wrote:
On Tue, Aug 06, 2013 at 06:18:39PM +0100, Michael McMahon wrote:
Documenting in release notes is okay too, but I suspect developers are not
likely to look there at first anyway. Thinking aloud, it would be nice if
some kind of annotation could be associated with the affected constructors
such that a more meaningful/customized error message could be emitted by
javac. But, perhaps there aren't sufficient other use cases to justify that.
Many of us use Eclipse, NetBeans, and JavaDoc.
So if we just had a comment in the JavaDoc, saying this was fixed, and what to
do, that ought to be more than adequate, and would prevent missing it if you
didn't see the relnotes.
Matthew.
