Improve docs.

Author: jpountz

lucene/core/src/java/org/apache/lucene/index/PostingsEnum.java

@@ -101,7 +101,9 @@ protected PostingsEnum() {}
 
   /**
    * Fill a buffer of doc IDs and frequencies with some number of doc IDs and their corresponding
-   * frequencies, starting at the current doc ID, and ending before {@code upTo}.
+   * frequencies, starting at the current doc ID, and ending before {@code upTo}. Because it starts
+   * on the current doc ID, it is illegal to call this method if the {@link #docID() current doc ID}
+   * is {@code -1}.
    *
    * <p>An empty buffer after this method returns indicates that there are no postings left between
    * the current doc ID and {@code upTo}.

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

@@ -80,7 +80,8 @@ public int advanceShallow(int target) throws IOException {
 
   /**
    * Return a new batch of doc IDs and scores, starting at the current doc ID, and ending before
-   * {@code upTo}.
+   * {@code upTo}. Because it starts on the current doc ID, it is illegal to call this method if the
+   * {@link #docID() current doc ID} is {@code -1}.
    *
    * <p>An empty return value indicates that there are no postings left between the current doc ID
    * and {@code upTo}.

lucene/core/src/test/org/apache/lucene/search/TestSimpleSearchEquivalence.java

@@ -37,7 +37,6 @@ public void testTermVersusBooleanOr() throws Exception {
     BooleanQuery.Builder q2 = new BooleanQuery.Builder();
     q2.add(new TermQuery(t1), Occur.SHOULD);
     q2.add(new TermQuery(t2), Occur.SHOULD);
-
     assertSubsetOf(q1, q2.build());
   }