You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Mark Miller <ma...@gmail.com> on 2009/09/28 21:22:45 UTC
Hits deprecated note is wrong
Bummer - through a user, just found out we missed correcting the docs
for moving from Hits. He was quite perturbed ;)
* @deprecated
* see {@link TopScoreDocCollector} and {@link TopDocs} :<br>
* <pre>
* TopScoreDocCollector collector = new TopScoreDocCollector(hitsPerPage);
* searcher.search(query, collector);
* ScoreDoc[] hits = collector.topDocs().scoreDocs;
* for (int i = 0; i < hits.length; i++) {
* int docId = hits[i].doc;
* Document d = searcher.doc(docId);
* // do something with current hit
* ...
* </pre>
Nothing we can really do, but if for some reason we end up with a 2.9.1
rather than 3.0 next, we should fix. Hard enough to upgrade for some
without these mistakes :)
--
- 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
Re: Hits deprecated note is wrong
Posted by Michael McCandless <lu...@mikemccandless.com>.
It's too bad there's no way to express a "this code fragment should
compile" inside a javadoc (I think?).
Had we {@link ...}'d each method invocation we would have at least
seen javadoc warnings, but that's a real hassle.
Mike
On Wed, Sep 30, 2009 at 12:07 PM, Mark Miller <ma...@gmail.com> wrote:
> Shai Erera wrote:
>> We're giving users a wrong impression as if they really need to create
>> TSDC and this can confuse people (see other thread by Eks).
>>
> And even then, because Hits users tended to be less advanced users, they
> are likely to be confused with TSDC - this guy was like, what the heck,
> the class is abstract! What the heck am I supposed to do! He was quite
> confused :) Didn't see that static create method.
>
> No ones fault in particular - just a bummer.
>
> --
> - 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
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Hits deprecated note is wrong
Posted by Mark Miller <ma...@gmail.com>.
Shai Erera wrote:
> We're giving users a wrong impression as if they really need to create
> TSDC and this can confuse people (see other thread by Eks).
>
And even then, because Hits users tended to be less advanced users, they
are likely to be confused with TSDC - this guy was like, what the heck,
the class is abstract! What the heck am I supposed to do! He was quite
confused :) Didn't see that static create method.
No ones fault in particular - just a bummer.
--
- 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
Re: Hits deprecated note is wrong
Posted by Mark Miller <ma...@gmail.com>.
Yeah I agree Shai - we want to point to search(Query, int) - but I think
its too late! Hits should be removed in 3.0.
I think elaborating on the docs for docsScoredInOrder is great idea for
3.0 though.
We might as well open an issue to give others a chance to comment about
the doc improvements (not that anyone is sure too ...)
- Mark
Shai Erera wrote:
> BTW Mark, I think the deprecation message in Hits should not even
> mention TSDC, but instead show the "fast" search method search(Query,
> int) or something like that. We're giving users a wrong impression as
> if they really need to create TSDC and this can confuse people (see
> other thread by Eks).
>
> Shai
>
> On Wed, Sep 30, 2009 at 5:52 PM, Shai Erera <serera@gmail.com
> <ma...@gmail.com>> wrote:
>
> I agree. The code sample was written before TSDC's create() method
> was written. I should have searched for TSDC references by text ...
> About docsScoredInOrder, I agree we should have elaborated on it
> in the javadocs. I think a sample code exists somewhere in
> CHANGES, but it wouldn't hurt to keep some sample code here too.
>
> Can such fixes go into 3.0? (I don't see why not). Should I open
> an issue, or do you want to quickly fix it?
>
> Shai
>
>
> On Mon, Sep 28, 2009 at 9:29 PM, Mark Miller
> <markrmiller@gmail.com <ma...@gmail.com>> wrote:
>
> Mark Miller wrote:
> > Bummer - through a user, just found out we missed correcting
> the docs
> > for moving from Hits. He was quite perturbed ;)
> >
> > * @deprecated
> > * see {@link TopScoreDocCollector} and {@link TopDocs} :<br>
> > * <pre>
> > * TopScoreDocCollector collector = new
> TopScoreDocCollector(hitsPerPage);
> > * searcher.search(query, collector);
> > * ScoreDoc[] hits = collector.topDocs().scoreDocs;
> > * for (int i = 0; i < hits.length; i++) {
> > * int docId = hits[i].doc;
> > * Document d = searcher.doc(docId);
> > * // do something with current hit
> > * ...
> > * </pre>
> >
> > Nothing we can really do, but if for some reason we end up
> with a 2.9.1
> > rather than 3.0 next, we should fix. Hard enough to upgrade
> for some
> > without these mistakes :)
> >
> >
> This is actually quite nasty - I can see why he was perturbed.
> We point
> to a class without a public constructor like it shows. Then if you
> manage to find the static constructor, there is no doc for the
> params.
> Then if you read the top, you see that you should know if you
> want to
> collect in order - which users likely don't. We obviously
> don't even
> want to point them to this class - but we do.
>
> --
> - Mark
>
> http://www.lucidimagination.com
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> <ma...@lucene.apache.org>
> For additional commands, e-mail:
> java-dev-help@lucene.apache.org
> <ma...@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
Re: Hits deprecated note is wrong
Posted by Shai Erera <se...@gmail.com>.
BTW Mark, I think the deprecation message in Hits should not even mention
TSDC, but instead show the "fast" search method search(Query, int) or
something like that. We're giving users a wrong impression as if they really
need to create TSDC and this can confuse people (see other thread by Eks).
Shai
On Wed, Sep 30, 2009 at 5:52 PM, Shai Erera <se...@gmail.com> wrote:
> I agree. The code sample was written before TSDC's create() method was
> written. I should have searched for TSDC references by text ...
> About docsScoredInOrder, I agree we should have elaborated on it in the
> javadocs. I think a sample code exists somewhere in CHANGES, but it wouldn't
> hurt to keep some sample code here too.
>
> Can such fixes go into 3.0? (I don't see why not). Should I open an issue,
> or do you want to quickly fix it?
>
> Shai
>
>
> On Mon, Sep 28, 2009 at 9:29 PM, Mark Miller <ma...@gmail.com>wrote:
>
>> Mark Miller wrote:
>> > Bummer - through a user, just found out we missed correcting the docs
>> > for moving from Hits. He was quite perturbed ;)
>> >
>> > * @deprecated
>> > * see {@link TopScoreDocCollector} and {@link TopDocs} :<br>
>> > * <pre>
>> > * TopScoreDocCollector collector = new
>> TopScoreDocCollector(hitsPerPage);
>> > * searcher.search(query, collector);
>> > * ScoreDoc[] hits = collector.topDocs().scoreDocs;
>> > * for (int i = 0; i < hits.length; i++) {
>> > * int docId = hits[i].doc;
>> > * Document d = searcher.doc(docId);
>> > * // do something with current hit
>> > * ...
>> > * </pre>
>> >
>> > Nothing we can really do, but if for some reason we end up with a 2.9.1
>> > rather than 3.0 next, we should fix. Hard enough to upgrade for some
>> > without these mistakes :)
>> >
>> >
>> This is actually quite nasty - I can see why he was perturbed. We point
>> to a class without a public constructor like it shows. Then if you
>> manage to find the static constructor, there is no doc for the params.
>> Then if you read the top, you see that you should know if you want to
>> collect in order - which users likely don't. We obviously don't even
>> want to point them to this class - but we do.
>>
>> --
>> - 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
>>
>>
>
Re: Hits deprecated note is wrong
Posted by Shai Erera <se...@gmail.com>.
I agree. The code sample was written before TSDC's create() method was
written. I should have searched for TSDC references by text ...
About docsScoredInOrder, I agree we should have elaborated on it in the
javadocs. I think a sample code exists somewhere in CHANGES, but it wouldn't
hurt to keep some sample code here too.
Can such fixes go into 3.0? (I don't see why not). Should I open an issue,
or do you want to quickly fix it?
Shai
On Mon, Sep 28, 2009 at 9:29 PM, Mark Miller <ma...@gmail.com> wrote:
> Mark Miller wrote:
> > Bummer - through a user, just found out we missed correcting the docs
> > for moving from Hits. He was quite perturbed ;)
> >
> > * @deprecated
> > * see {@link TopScoreDocCollector} and {@link TopDocs} :<br>
> > * <pre>
> > * TopScoreDocCollector collector = new
> TopScoreDocCollector(hitsPerPage);
> > * searcher.search(query, collector);
> > * ScoreDoc[] hits = collector.topDocs().scoreDocs;
> > * for (int i = 0; i < hits.length; i++) {
> > * int docId = hits[i].doc;
> > * Document d = searcher.doc(docId);
> > * // do something with current hit
> > * ...
> > * </pre>
> >
> > Nothing we can really do, but if for some reason we end up with a 2.9.1
> > rather than 3.0 next, we should fix. Hard enough to upgrade for some
> > without these mistakes :)
> >
> >
> This is actually quite nasty - I can see why he was perturbed. We point
> to a class without a public constructor like it shows. Then if you
> manage to find the static constructor, there is no doc for the params.
> Then if you read the top, you see that you should know if you want to
> collect in order - which users likely don't. We obviously don't even
> want to point them to this class - but we do.
>
> --
> - 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
>
>
Re: Hits deprecated note is wrong
Posted by Mark Miller <ma...@gmail.com>.
Mark Miller wrote:
> Bummer - through a user, just found out we missed correcting the docs
> for moving from Hits. He was quite perturbed ;)
>
> * @deprecated
> * see {@link TopScoreDocCollector} and {@link TopDocs} :<br>
> * <pre>
> * TopScoreDocCollector collector = new TopScoreDocCollector(hitsPerPage);
> * searcher.search(query, collector);
> * ScoreDoc[] hits = collector.topDocs().scoreDocs;
> * for (int i = 0; i < hits.length; i++) {
> * int docId = hits[i].doc;
> * Document d = searcher.doc(docId);
> * // do something with current hit
> * ...
> * </pre>
>
> Nothing we can really do, but if for some reason we end up with a 2.9.1
> rather than 3.0 next, we should fix. Hard enough to upgrade for some
> without these mistakes :)
>
>
This is actually quite nasty - I can see why he was perturbed. We point
to a class without a public constructor like it shows. Then if you
manage to find the static constructor, there is no doc for the params.
Then if you read the top, you see that you should know if you want to
collect in order - which users likely don't. We obviously don't even
want to point them to this class - but we do.
--
- 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