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:43:17 GMT
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)" <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
>>>
>>>       
>> ---------------------------------------------------------------------
>> 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