On 4 May 2011 13:10, sebb <seb...@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-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
