[jira] Commented: (LUCENE-1900) Confusing Javadoc in Searchable.java

["Mark Miller (JIRA)" <ji...@apache.org>]

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

Mark Miller commented on LUCENE-1900:
-------------------------------------

Yeah - could be more clear.

I agree that there doesn't appear to be a need to mark it as expert. And I guess we should just remove the part that mentions its involved in the weight? Or re word.

"This is used as an approximation of the number of documents in the index for scoring calculations."

Or something to that effect (namely, better). Perhaps approximation isnt even needed - 

"Because un-merged deleted docs still contribute to index statistics, this is used as the number of documents in the index for scoring calculations."

or ...

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