Improve Weight#count and IndexSearcher#count javadocs (#625)

Author: javanna

lucene/core/src/java/org/apache/lucene/search/IndexSearcher.java

@@ -440,7 +440,11 @@ public ScoreMode scoreMode() {
     }
   }
 
-  /** Count how many documents match the given query. */
+  /**
+   * Count how many documents match the given query. May be faster than counting number of hits by
+   * collecting all matches, as the number of hits is retrieved from the index statistics when
+   * possible.
+   */
   public int count(Query query) throws IOException {
     query = rewrite(query);
     final Weight weight = createWeight(query, ScoreMode.COMPLETE_NO_SCORES, 1);

lucene/core/src/java/org/apache/lucene/search/Weight.java

@@ -178,13 +178,13 @@ public BulkScorer bulkScorer(LeafReaderContext context) throws IOException {
    * Counts the number of live documents that match a given {@link Weight#parentQuery} in a leaf.
    *
    * <p>The default implementation returns -1 for every query. This indicates that the count could
-   * not be computed in O(1) time.
+   * not be computed in sub-linear time.
    *
-   * <p>Specific query classes should override it to provide other accurate O(1) implementations
-   * (that actually return the count). Look at {@link MatchAllDocsQuery#createWeight(IndexSearcher,
-   * ScoreMode, float)} for an example
+   * <p>Specific query classes should override it to provide other accurate sub-linear
+   * implementations (that actually return the count). Look at {@link
+   * MatchAllDocsQuery#createWeight(IndexSearcher, ScoreMode, float)} for an example
    *
-   * <p>We use this property of the function to to count hits in {@link IndexSearcher#count(Query)}.
+   * <p>We use this property of the function to count hits in {@link IndexSearcher#count(Query)}.
    *
    * @param context the {@link org.apache.lucene.index.LeafReaderContext} for which to return the
    *     count.