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/lucene/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 .incrementToken()
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<rcm...@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<markrmil...@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 readability. >> Once you know whats up, its not too much different. I just have found myself >> having to refigure out whats up (a short task to be sure) over again after 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 really >> wouldnt let that stop you ... >>> >>> On Mon, Jun 15, 2009 at 1:55 PM, Mark Miller<markrmil...@gmail.com> wrote: >>> >>>> >>>> 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 includes >>>> complaints), >>>> I think its all good. >>>> >>>>> >>>>> but 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 no >>>>> tests, its impossible to verify the conversion is correct. >>>>> >>>>> >>>> >>>> Thanks for pointing that out. We probably get lazy with tests, especially >>>> 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 sure >>>> 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 here >>>> 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-unsubscr...@lucene.apache.org >>>> For additional commands, e-mail: java-dev-h...@lucene.apache.org >>>> >>>> >>>> >>> >>> >>> >>> >> >> >> -- >> - Mark >> >> http://www.lucidimagination.com >> >> >> >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: java-dev-unsubscr...@lucene.apache.org >> For additional commands, e-mail: java-dev-h...@lucene.apache.org >> >> > > > > -- > Robert Muir > rcm...@gmail.com > -- Robert Muir rcm...@gmail.com --------------------------------------------------------------------- To unsubscribe, e-mail: java-dev-unsubscr...@lucene.apache.org For additional commands, e-mail: java-dev-h...@lucene.apache.org
