This is excellent feedback, Robert!
I agree this is confusing; especially having a deprecated API and only a
experimental one that replaces the old one. We need to change that.
And I don't like the *useNewAPI*() methods either. I spent a lot of time
thinking about backwards compatibility for this API. It's tricky to do
without sacrificing performance. In API patches I find myself spending
more time for backwards-compatibility than for the actual new feature! :(
I'll try to think about how to simplify this confusing old/new API mix.
However, we need to make the decisions:
a) if we want to release this new API with 2.9,
b) if yes to a), if we want to remove the old API in 3.0?
If yes to a) and no to b), then we'll have to support both APIs for a
presumably very long time, so we then need to have a better solution for
the backwards-compatibility here.
-Michael
On 6/15/09 1:09 PM, Robert Muir wrote:
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
