I agree that its not necessary - and like I said in the other email - I'm not actually trying to get you to change it (much more important changes to argue for than javadoc), but I still disagree. I like those links ;) In my judgment, I never know what I want as a link ahead of time - I end up using them all over the place - it depends on the situation every time. I like them available though.
I suppose in my view, I don't see them as making the javadoc harder to read - I like things linky so I can click on any random occurrence I am focusing on. I know its personal taste though - similar to code formatting. - Mark Uwe Schindler wrote: > 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 > > -- - Mark http://www.lucidimagination.com --------------------------------------------------------------------- To unsubscribe, e-mail: java-dev-unsubscr...@lucene.apache.org For additional commands, e-mail: java-dev-h...@lucene.apache.org
