Mailing-List: contact java-dev-help@lucene.apache.org; run by ezmlm
Precedence: bulk
Reply-To: java-dev@lucene.apache.org
Received-SPF: pass (nike.apache.org: domain of markrmiller@gmail.com
 designates 209.85.221.192 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=message-id:date:from:user-agent:mime-version:to:subject:references
         :in-reply-to:x-enigmail-version:content-type
         :content-transfer-encoding;
        b=oeQV7x+its14Q+DfC03+pOogeSv4r3zJ5a+4E1VrPRanmJ74BbmOch7dbLE8FXIudk
         LEs6X7eSs9rDPmVUKIbrKE5Ckiha2dXxWTEt5MNJ4onemYvvkklMql79nUdblJ2N7ljR
         33+LOFWH5glUJT2lmk4//SdUQ4fmbnlhu6fZc=
Message-ID: <4A9A9CDC.7040003@gmail.com>
Date: Sun, 30 Aug 2009 11:38:04 -0400
From: Mark Miller <markrmiller@gmail.com>
User-Agent: Thunderbird 2.0.0.23 (X11/20090817)
MIME-Version: 1.0
To: "java-dev@lucene.apache.org" <java-dev@lucene.apache.org>
Subject: Re: [jira] Updated: (LUCENE-1875) Javadoc of TokenStream.end()
 somehow
 confusing
References: <1654500732.1251627452755.JavaMail.jira@brutus>
 <A5AB7689-7148-49C3-989F-8A8637FA4A6D@gmail.com>
In-Reply-To: <A5AB7689-7148-49C3-989F-8A8637FA4A6D@gmail.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

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