- Paul's Javadoc improvements from bug 33678: http://issues.apache.org/bugzilla/show_bug.cgi?id=33678

git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@155607 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/lucene/search/HitCollector.java

@@ -17,6 +17,8 @@ package org.apache.lucene.search;
  */
 
 /** Lower-level search API.
+ * <br>HitCollectors are primarily meant to be used to implement queries,
+ * sorting and filtering.
  * @see Searcher#search(Query,HitCollector)
  * @version $Id$
  */

src/java/org/apache/lucene/search/Searchable.java

@@ -24,14 +24,20 @@ import org.apache.lucene.index.IndexReader;       // for javadoc
 
 /** The interface for search implementations.
  *
- * <p>Implementations provide search over a single index, over multiple
+ * <p>Searchable is the abstract network protocol for searching. 
+ * Implementations provide search over a single index, over multiple
  * indices, and over indices on remote servers.
+ *
+ * <p>Queries, filters and sort criteria are designed to be compact so that
+ * they may be efficiently passed to a remote index, with only the top-scoring
+ * hits being returned, rather than every non-zero scoring hit.
  */
 public interface Searchable extends java.rmi.Remote {
   /** Lower-level search API.
    *
    * <p>{@link HitCollector#collect(int,float)} is called for every non-zero
    * scoring document.
+   * <br>HitCollector-based access to remote indexes is discouraged.
    *
    * <p>Applications should only use this if they need <i>all</i> of the
    * matching documents.  The high-level search API ({@link

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

@@ -21,7 +21,13 @@ import java.io.IOException;
 import org.apache.lucene.index.IndexReader;
 
 /** Expert: Calculate query weights and build query scorers.
- * <br>A <code>Weight</code> is used in the following way:
+ * <p>
+ * The purpose of Weight is to make it so that searching does not modify
+ * a Query, so that a Query instance can be reused. <br>
+ * Searcher dependent state of the query should reside in the Weight. <br>
+ * IndexReader dependent state should reside in the Scorer.
+ * <p>
+ * A <code>Weight</code> is used in the following way:
  * <ol>
  * <li>A <code>Weight</code> is constructed by a top-level query,
  *     given a <code>Searcher</code> ({@link Query#createWeight(Searcher)}).