add javadocs NOTE stating that the core collectors pre-allocate the full array[numHits] up front

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

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

@@ -173,6 +173,9 @@ public abstract class FieldValueHitQueue extends PriorityQueue {
   /**
    * Creates a hit queue sorted by the given list of fields.
    * 
+   * <p><b>NOTE</b>: The instances returned by this method
+   * pre-allocate a full array of length <code>numHits</code>.
+   * 
    * @param fields
    *          SortField array we are sorting by in priority order (highest
    *          priority first); cannot be <code>null</code> or empty

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

@@ -53,6 +53,9 @@ final class HitQueue extends PriorityQueue {
    * }
    * </pre>
    * 
+   * <p><b>NOTE</b>: This class pre-allocate a full array of
+   * length <code>size</code>.
+   * 
    * @param size
    *          the requested size of this queue.
    * @param prePopulate

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

@@ -810,7 +810,12 @@ public abstract class TopFieldCollector extends TopDocsCollector {
   }
 
   /**
-   * Creates a new {@link TopFieldCollector} from the given arguments.
+   * Creates a new {@link TopFieldCollector} from the given
+   * arguments.
+   *
+   * <p><b>NOTE</b>: The instances returned by this method
+   * pre-allocate a full array of length
+   * <code>numHits</code>.
    * 
    * @param sort
    *          the sort criteria (SortFields).

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

@@ -80,6 +80,11 @@ public abstract class TopScoreDocCollector extends TopDocsCollector {
    * Creates a new {@link TopScoreDocCollector} given the number of hits to
    * collect and whether documents are scored in order by the input
    * {@link Scorer} to {@link #setScorer(Scorer)}.
+   *
+   * <p><b>NOTE</b>: The instances returned by this method
+   * pre-allocate a full array of length
+   * <code>numHits</code>, and fill the array with sentinel
+   * objects.
    */
   public static TopScoreDocCollector create(int numHits, boolean docsScoredInOrder) {
     

src/java/org/apache/lucene/util/PriorityQueue.java

@@ -18,8 +18,13 @@ package org.apache.lucene.util;
  */
 
 /** A PriorityQueue maintains a partial ordering of its elements such that the
-  least element can always be found in constant time.  Put()'s and pop()'s
-  require log(size) time. */
+ * least element can always be found in constant time.  Put()'s and pop()'s
+ * require log(size) time.
+ *
+ * <p><b>NOTE</b>: This class pre-allocates a full array of
+ * length <code>maxSize+1</code>, in {@link #initialize}.
+  * 
+*/
 public abstract class PriorityQueue {
   private int size;
   private int maxSize;