commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stephen Colebourne <scolebou...@joda.org>
Subject Re: svn commit: r1099416 - /commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/text/FormattableUtils.java
Date Wed, 04 May 2011 12:17:44 GMT
On 4 May 2011 13:10, sebb <sebbaz@gmail.com> 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:

http://people.apache.org/~bayard/commons-lang3-3.0-RC3/site/apidocs/org/apache/commons/lang3/text/package-summary.html
http://people.apache.org/~bayard/commons-lang3-3.0-RC3/site/apidocs/org/apache/commons/lang3/text/FormattableUtils.html

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).

Stephen

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message