On 4/20/11 5:07 AM, Lance Andersen - Oracle wrote:
On Apr 20, 2011, at 7:41 AM, Doug Lea wrote:
On 04/19/11 21:07, David Holmes wrote:
Hi Mike,
Mike Duigou said the following on 04/20/11 08:00:
Hello All;
Another collections javadoc review request. This change links the "(optional)"
notes in on various Collection methods to text which explains why they are not
thrown by all collections.
Generally looks good. I think you should revert this additional change in
Collection.java:
! *
"null" is used all over the place without being code font, including other
@throws NullPointerException.
This, along with literals "true" and "false" are not code-fonted
very consistently. Someday someone should do a big consistency pass
across the whole code base.
Perhaps we can document what we believe the standards should be WRT when to use
{@code} . I am sure I have clean up to do throughout the JDBC as well for
consistency in this area
I think there is a preference for {@code foobar} over <code>foobar</code> but
I'm not sure it's written down anywhere. The "What's new in Javadoc 5.0" page
[1] says that "{@code abc} is equivalent to <code>{@literal abc}</code>." This
is useful in case "abc" contains angle brackets, which needn't be escaped if
@code is used. This is a good reason to use @code instead of <code>...</code>.
However, I think that <code> and @code are overused in general. If it's used
for an actual code fragment, fine, but I really think it's unnecessary for
single words such as true, false, and null used within running text. To use
this specific example, is
@throws NullPointerException if the specified array is {@code null}
really preferable to
@throws NullPointerException if the specified array is null
? To my eye, the additional markup garbages up the javadoc source, makes it
harder to edit, and it makes the formatted output harder to read. The most
egregious example is {@code try}-with-resources. Check out java.lang.Throwable
to see it in action.
Perhaps @code is warranted in cases that would otherwise be ambiguous, such as
create a long array
versus
create a {@code long} array
But these cases are relatively rare.
s'marks
[1]
http://download.oracle.com/javase/6/docs/technotes/guides/javadoc/whatsnew-1.5.0.html
