Remaining doclint issues in java.net
chris.hegarty at oracle.com
Mon Jul 29 14:28:36 UTC 2013
There are two remaining doclint warnings in the java.net package.
src/share/classes/java/net/DatagramPacket.java:142: warning: no @throws
public DatagramPacket(byte buf, int offset, int length,
src/share/classes/java/net/DatagramPacket.java:178: warning: no @throws
public DatagramPacket(byte buf, int length,
These are caused by no @throws SE declaration on the constructors.
As it happens 'throws SE' was incorrectly added to these constructors
when introduced in 1.4. The original API specified that SE was thrown
when the given SocketAddress was not supported. That was later changed
to throw IAE, in 1.4.2. These constructor now can never throw SE.
Removing 'throws SE' from the method declaration is a binary compatible
change, but not source compatible ( XXX is never thrown in body of
corresponding try statement ). I don't think breaking source
compatibility for this kind of change is justified. If it is, then the
solution is to simply remove 'throws SE'.
Back in the real world, I guess we need to come up with some wording for
the '@throws SE' declaration. Something vague like "If an I/O Exception
occurs", or can we put something stronger like "will never be thrown" ??
More information about the core-libs-dev