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