lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Uwe Schindler" <...@thetaphi.de>
Subject RE: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end() somehow confusing
Date Sun, 30 Aug 2009 15:44:15 GMT
No problem, see my other mail! I can revert the @link changes. By the way, I
noticed shortly, that @code is Java 5 only. So I could replace it by
<code></code>.

For me the whole class Javadocs were a little bit over-linkified with links
pointing to the same class itself. I only wanted to remove links (as the
guide from sun notes), that are somehow pointing to the exact same class the
description is about (in the class description).

I am a real fan of linking everything, so links between methods is very
important!

-----
Uwe Schindler
H.-H.-Meier-Allee 63, D-28213 Bremen
http://www.thetaphi.de
eMail: uwe@thetaphi.de


> -----Original Message-----
> From: Mark Miller [mailto:markrmiller@gmail.com]
> Sent: Sunday, August 30, 2009 5:38 PM
> To: java-dev@lucene.apache.org
> Subject: Re: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end()
> somehow confusing
> 
> To add to my argument (and I'm not trying to get you to change this
> patch by the way - its just javadoc, and I'm more interested in the
> argument than the results this morning ;) )
> 
> You could make a similar argument that links from one method referencing
> another in the same class are unneeded - you are already at the page.
> But they nicely scroll you to what you want to see. Same with the class
> link itself - if you are at the bottom of a long class and click the
> class link, it takes you to the top and definition of the class - the
> same way that when I am in next(), I can click a link to get to the
> increment() definition.
> 
> - Mark
> 
> Mark Miller wrote:
> > 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)" <jira@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-unsubscribe@lucene.apache.org
> >> For additional commands, e-mail: java-dev-help@lucene.apache.org
> >>
> 
> 
> --
> - Mark
> 
> http://www.lucidimagination.com
> 
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org



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


Mime
View raw message