You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by "Uwe Schindler (JIRA)" <ji...@apache.org> on 2009/08/30 11:47:32 UTC
[jira] Created: (LUCENE-1875) Javadoc of TokenStream.end() somehow
confusing
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
Fix For: 2.9
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
[jira] Assigned: (LUCENE-1875) Javadoc of TokenStream.end() somehow
confusing
Posted by "Uwe Schindler (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1875?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Uwe Schindler reassigned LUCENE-1875:
-------------------------------------
Assignee: Uwe Schindler
> 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
[jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end() somehow
confusing
Posted by "Uwe Schindler (JIRA)" <ji...@apache.org>.
[ 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
Replaces {@code ...} by javadoc 1.4 compatible <code/>.
Will commit soon.
> 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, 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
[jira] Resolved: (LUCENE-1875) Javadoc of TokenStream.end() somehow
confusing
Posted by "Uwe Schindler (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/LUCENE-1875?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Uwe Schindler resolved LUCENE-1875.
-----------------------------------
Resolution: Fixed
Committed revision: 809381
> 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, 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
Re: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end() somehow
confusing
Posted by Mark Miller <ma...@gmail.com>.
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: uwe@thetaphi.de
>
>
>> -----Original Message-----
>> From: Mark Miller [mailto:markrmiller@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)" <ji...@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
>>>
>>>
>> ---------------------------------------------------------------------
>> 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
>
>
--
- 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
RE: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end() somehow confusing
Posted by Uwe Schindler <uw...@thetaphi.de>.
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: uwe@thetaphi.de
> -----Original Message-----
> From: Mark Miller [mailto:markrmiller@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)" <ji...@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
> >
>
> ---------------------------------------------------------------------
> 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
Re: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end() somehow
confusing
Posted by Mark Miller <ma...@gmail.com>.
No, no, I wasn't arguing for a revert - more interested in exploring the
topic :)
If you think its cleaner, you did way more on the TokenStream API stuff
than me and I think your javadoc
pref on it should outweigh mine.
- Mark
Uwe Schindler wrote:
> 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)" <ji...@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
>
>
--
- 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
RE: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end() somehow confusing
Posted by Uwe Schindler <uw...@thetaphi.de>.
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)" <ji...@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
Re: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end() somehow
confusing
Posted by Mark Miller <ma...@gmail.com>.
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)" <ji...@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
Re: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end() somehow confusing
Posted by Mark Miller <ma...@gmail.com>.
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)" <ji...@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
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
[jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end() somehow
confusing
Posted by "Uwe Schindler (JIRA)" <ji...@apache.org>.
[ 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