lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Doron Cohen (JIRA)" <j...@apache.org>
Subject [jira] Commented: (LUCENE-1900) Confusing Javadoc in Searchable.java
Date Tue, 08 Sep 2009 17:37:58 GMT

    [ https://issues.apache.org/jira/browse/LUCENE-1900?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12752625#action_12752625
] 

Doron Cohen commented on LUCENE-1900:
-------------------------------------

hi.., I think the 'expert' is here because it reveals internal information which users should
not rely on unless understanding exactly what they are doing with it. - well, at least as
internal as are the unstable docids - on the other hand, IndexReader.maxDoc() is not marked
'expert', so perhaps this one also should not be marked 'expert'.

Similarity.idfExplain(Term,Searcher) explains nicely why maxDoc() is used rather than numDocs():
{noformat}
   * Note that {@link Searcher#maxDoc()} is used instead of
   * {@link org.apache.lucene.index.IndexReader#numDocs()} because it is
   * proportional to {@link Searcher#docFreq(Term)} , i.e., when one is
   * inaccurate, so is the other, and in the same direction.
{noformat}

> Confusing Javadoc in Searchable.java
> ------------------------------------
>
>                 Key: LUCENE-1900
>                 URL: https://issues.apache.org/jira/browse/LUCENE-1900
>             Project: Lucene - Java
>          Issue Type: Bug
>          Components: Search
>    Affects Versions: 2.9
>            Reporter: Nadav Har'El
>            Assignee: Mark Miller
>            Priority: Trivial
>
> In Searchable.java, the javadoc for maxdoc() is:
>   /** Expert: Returns one greater than the largest possible document number.
>    * Called by search code to compute term weights.
>    * @see org.apache.lucene.index.IndexReader#maxDoc()
> The qualification "expert" and the statement "called by search code to compute term weights"
is a bit confusing, It implies that maxdoc() somehow computes weights, which is obviously
not true (what it does is explained in the other sentence). Maybe it is used as one factor
of the weight, but do we really need to mention this here? 

-- 
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


Mime
View raw message