commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stephen Colebourne <>
Subject Re: svn commit: r1099416 - /commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/text/
Date Wed, 04 May 2011 12:17:44 GMT
On 4 May 2011 13:10, sebb <> wrote:
>>     /**
>> -     * <p>{@link FormattableUtils} instances should NOT be constructed in
>> +     * <p>{@code FormattableUtils} instances should NOT be constructed in
> What's wrong with @link here?

In general, it is not advisable to use @link in the first sentence of
a Javadoc class or method description. That is because it appears
linked in the summary documentation:

These links (especially at the class level) are distracting when
viewing that summary.

Thus, it is better to use @code in the first sentence, and @link for
the main description if necessary (but only for the first link in any
doc). More generally, I would say that @link is a slightly over-used,
as there is frequently a link available via a method signature anyway
(not relevant in this case).

I'd also note that Oracle has recently had a mail recommending that
null, true and false are NOT surrounded by @code (for readbility).


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message