I cite the guide from Sun
(http://java.sun.com/j2se/javadoc/writingdoccomments/):
------------------------------------------------------
Use in-line links economically
You are encouraged to add links for API names (listed immediately above)
using the {...@link} tag. It is not necessary to add links for all API names in
a doc comment. Because links call attention to themselves (by their color
and underline in HTML, and by their length in source code doc comments), it
can make the comments more difficult to read if used profusely. We therefore
recommend adding a link to an API name if:
- The user might actually want to click on it for more information (in your
judgment), and
- Only for the first occurrence of each API name in the doc comment (don't
bother repeating a link)
Our audience is advanced (not novice) programmers, so it is generally not
necessary to link to API in the java.lang package (such as String), or other
API you feel would be well-known.
------------------------------------------------------
The general formatting of class names could be solved by using {...@link ...}
for foreign ones and {...@code ...} for the class name itself.
-----
Uwe Schindler
H.-H.-Meier-Allee 63, D-28213 Bremen
http://www.thetaphi.de
eMail: u...@thetaphi.de
> -----Original Message-----
> From: Mark Miller [mailto:markrmil...@gmail.com]
> Sent: Sunday, August 30, 2009 5:03 PM
> To: java-dev@lucene.apache.org
> Subject: Re: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end()
> somehow confusing
>
> That depends - the links may end up in summaries on different pages
> (first sentence as an exaple) - it also provides a consistent
> formatting for class names so that they pop silmialry everywhere. I
> don't agree with "it makes no sense." I'd make every classname
> everywhere a link if I could.
>
> - Mark
>
> http://www.lucidimagination.com (mobile)
>
> On Aug 30, 2009, at 6:17 AM, "Uwe Schindler (JIRA)" <j...@apache.org>
> wrote:
>
> >
> > [ https://issues.apache.org/jira/browse/LUCENE-
> 1875?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
> > ]
> >
> > Uwe Schindler updated LUCENE-1875:
> > ----------------------------------
> >
> > Attachment: LUCENE-1875.patch
> >
> > Patxh with changed end() javadocs. This patch also removes the
> > {...@link TokenStream}s inside TokenStream.java (it does not make sense
> > to link to the same doc page itsself).
> >
> >> Javadoc of TokenStream.end() somehow confusing
> >> ----------------------------------------------
> >>
> >> Key: LUCENE-1875
> >> URL: https://issues.apache.org/jira/browse/LUCENE-1875
> >> Project: Lucene - Java
> >> Issue Type: Bug
> >> Components: Analysis
> >> Affects Versions: 2.9
> >> Reporter: Uwe Schindler
> >> Assignee: Uwe Schindler
> >> Fix For: 2.9
> >>
> >> Attachments: LUCENE-1875.patch
> >>
> >>
> >> The Javadocs of TokenStream.end() are somehow confusing, because
> >> they also refer to the old TokenStream API ("after next() returned
> >> null"). But one who implements his TokenStream with the old API
> >> cannot make use of the end() feature, as he would not use
> >> attributes and so cannot update the end offsets (he could, but then
> >> he should rewrite the whole TokenStream). To be conform to the old
> >> API, there must be an end(Token) method, which we will not add.
> >> I would drop the old API from this docs.
> >
> > --
> > This message is automatically generated by JIRA.
> > -
> > You can reply to this email to add a comment to the issue online.
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: java-dev-unsubscr...@lucene.apache.org
> > For additional commands, e-mail: java-dev-h...@lucene.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscr...@lucene.apache.org
> For additional commands, e-mail: java-dev-h...@lucene.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: java-dev-h...@lucene.apache.org
