Review : 6546713: Link optional in Collection exception documentation to explanation

[Stuart Marks]

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