lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mark Miller <markrmil...@gmail.com>
Subject Re: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end() somehow confusing
Date Sun, 30 Aug 2009 15:47:17 GMT
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)" <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
>
>   


-- 
- 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


Mime
View raw message