Mailing-List: contact java-dev-help@lucene.apache.org; run by ezmlm
Precedence: bulk
Reply-To: java-dev@lucene.apache.org
Received-SPF: pass (athena.apache.org: domain of rcmuir@gmail.com designates
 209.85.132.251 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :content-type:content-transfer-encoding;
        b=avW1qRyds4ljF2GqOxsfsgSs+DsVs44XmBz/qIBIglDxs2Hj6A7I4O842rK07mZo+X
         LcYZ++blG5qMZC8y9zk60eqCeMsoZbo6j7350gEbEOIzdmKkeTwcdNS2qn2BXi86CN/2
         EAbwqV1YVjQQ6R6JdvFdvwtCpvvdUh2U8f4mQ=
MIME-Version: 1.0
In-Reply-To: <8f0ad1f30906151245p290bb3ddq6bf7af23e9b691f5@mail.gmail.com>
References: <85d3c3b60906091932i591ef6f4gcc950586b15d4506@mail.gmail.com>
	 <4A34614C.7000004@gmail.com>
	 <3276E8A9-84A5-415A-A25A-39EDB39DFC38@apache.org>
	 <c68e39170906151014n70db7232jd71511fcc1a29cc7@mail.gmail.com>
	 <4A3682FF.4090404@gmail.com>
	 <8f0ad1f30906151031n5cbdf563vac86bd7fa784c315@mail.gmail.com>
	 <4A368B2E.6000607@gmail.com>
	 <8f0ad1f30906151121r1c1687a4o4efca0fa319ef01c@mail.gmail.com>
	 <4A369892.1080401@gmail.com>
	 <8f0ad1f30906151245p290bb3ddq6bf7af23e9b691f5@mail.gmail.com>
Date: Mon, 15 Jun 2009 16:09:46 -0400
Message-ID: <8f0ad1f30906151309i79ce7327hf42b3ec2cdf5227e@mail.gmail.com>
Subject: Re: New Token API was Re: Payloads and TrieRangeQuery
From: Robert Muir <rcmuir@gmail.com>
To: java-dev@lucene.apache.org
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

let me try some slightly more constructive feedback:

new user looks at TokenStream javadocs:
http://hudson.zones.apache.org/hudson/job/Lucene-trunk/javadoc/org/apache/l=
ucene/analysis/TokenStream.html
immediately they see deprecated, text in red with the words
"experimental", warnings in bold, the whole thing is scary!
due to the use of 'e.g.' the javadoc for .incrementToken() is cut off
in a bad way, and its probably the most important method to a new
user!
there's also a stray bold tag gone haywire somewhere, possibly .incrementTo=
ken()

from a technical perspective, the documentation is excellent! but for
a new user unfamiliar with lucene, its unclear exactly what steps to
take: use the scary red experimental api or the old deprecated one?

theres also some fairly advanced stuff such as .captureState and
.restoreState that might be better in a different place.

finally, the .setUseNewAPI() and .setUseNewAPIDefault() are confusing
[one is static, one is not], especially because it states all streams
and filters in one chain must use the same API, is there a way to
simplify this?

i'm really terrible with javadocs myself, but perhaps we can come up
with a way to improve the presentation... maybe that will make the
difference.

On Mon, Jun 15, 2009 at 3:45 PM, Robert Muir<rcmuir@gmail.com> wrote:
> Mark, I'll see if I can get tests produced for some of those analyzers.
>
> as a new user of the new api myself, I think I can safely say the most
> confusing thing about it is having the old deprecated API mixed in the
> javadocs with it :)
>
> On Mon, Jun 15, 2009 at 2:53 PM, Mark Miller<markrmiller@gmail.com> wrote=
:
>> Robert Muir wrote:
>>>
>>> Mark, I created an issue for this.
>>>
>>
>> Thanks Robert, great idea.
>>>
>>> I just think you know, converting an analyzer to the new api is really
>>> not that bad.
>>>
>>
>> I don't either. I'm really just complaining about the initial readabilit=
y.
>> Once you know whats up, its not too much different. I just have found my=
self
>> having to refigure out whats up (a short task to be sure) over again aft=
er I
>> leave it for a while. With the old one, everything was just kind of
>> immediately self evident.
>>
>> That makes me think new users might be a little more confused when they
>> first meet again. I'm not a new user though, so its only a guess really.
>>>
>>> reverse engineering what one of them does is not necessarily obvious,
>>> and is completely unrelated but necessary if they are to be migrated.
>>>
>>> I'd be willing to assist with some of this but I don't want to really
>>> work the issue if its gonna be a waste of time at the end of the
>>> day...
>>>
>>
>> The chances of this issue being fully reverted are so remote that I real=
ly
>> wouldnt let that stop you ...
>>>
>>> On Mon, Jun 15, 2009 at 1:55 PM, Mark Miller<markrmiller@gmail.com> wro=
te:
>>>
>>>>
>>>> Robert Muir wrote:
>>>>
>>>>>>
>>>>>> As Lucene's contrib hasn't been fully converted either (and its been
>>>>>> quite
>>>>>> some time now), someone has probably heard that groan before.
>>>>>>
>>>>>>
>>>>>
>>>>> hope this doesn't sound like a complaint,
>>>>>
>>>>
>>>> Complaints are fine in any case. Every now and then, it might cause a
>>>> little
>>>> rant from me or something, but please don't let that dissuade you :)
>>>> Who doesnt like to rant and rave now and then. As long as thoughts and
>>>> opinions are coming out in a non negative way (which certainly include=
s
>>>> complaints),
>>>> I think its all good.
>>>>
>>>>>
>>>>> =C2=A0but in my opinion this is
>>>>> because many do not have any tests.
>>>>> I converted a few of these and its just grunt work but if there are n=
o
>>>>> tests, its impossible to verify the conversion is correct.
>>>>>
>>>>>
>>>>
>>>> Thanks for pointing that out. We probably get lazy with tests, especia=
lly
>>>> in
>>>> contrib, and this brings up a good point - we should probably push
>>>> for tests or write them before committing more often. Sometimes I'm su=
re
>>>> it
>>>> just comes downto a tradeoff though - no resources at the time,
>>>> the class looked clear cut, and it was just contrib anyway. But then h=
ere
>>>> we
>>>> are ... a healthy dose of grunt work is bad enough when you have tests=
 to
>>>> check it.
>>>>
>>>> --
>>>> - 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
>>>>
>>>>
>>>>
>>>
>>>
>>>
>>>
>>
>>
>> --
>> - 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
>>
>>
>
>
>
> --
> Robert Muir
> rcmuir@gmail.com
>


--=20
Robert Muir
rcmuir@gmail.com

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