improve comments; throw UOE from BS.freq() since it's not a doc-at-a-time scorer

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

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

@@ -332,7 +332,14 @@ public class BooleanQuery extends Query implements Iterable<BooleanClause> {
           optional.add(subScorer);
         }
       }
-      
+
+      // NOTE: we could also use BooleanScorer, if we knew
+      // this BooleanQuery was embedded in another
+      // BooleanQuery that was also using BooleanScorer (ie,
+      // BooleanScorer can nest).  But this is hard to
+      // detect and we never do so today... (ie, we only
+      // return BooleanScorer for topScorer):
+
       // Check if we can return a BooleanScorer
       if (!scoreDocsInOrder && topScorer && required.size() == 0) {
         return new BooleanScorer(this, disableCoord, minNrShouldMatch, optional, prohibited, maxCoord);

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

@@ -254,7 +254,12 @@ final class BooleanScorer extends Scorer {
           // clauses
           //&& (current.bits & requiredMask) == requiredMask) {
           
-          // TODO: can we remove this?  
+          // NOTE: Lucene always passes max =
+          // Integer.MAX_VALUE today, because we never embed
+          // a BooleanScorer inside another (even though
+          // that should work)... but in theory an outside
+          // app could pass a different max so we must check
+          // it:
           if (current.doc >= max){
             tmp = current;
             current = current.next;
@@ -318,7 +323,7 @@ final class BooleanScorer extends Scorer {
 
   @Override
   public float freq() throws IOException {
-    return current.coord;
+    throw new UnsupportedOperationException();
   }
 
   @Override