The BulkScorer#score javadoc example calls Scorer.advance() and nextDoc(), which Scorer has not had since 5.5.0

The javadoc of BulkScorer#score(LeafCollector, Bits, int, int) states the window contract (ignore documents before min, return a value >= max) and then shows "a Scorer-based implementation" in 16 lines of Java. Two of them call scorer.advance(min) and scorer.nextDoc(). Scorer has had neither method since LUCENE-6919 (5.5.0) made it expose iterator() instead of extending DocIdSetIterator, so the example fails with two cannot find symbol errors on every release from 5.5.0 to 10.6.0 and on main.

The example was valid when it was written: up to 5.4.1 Scorer extended DocIdSetIterator (compiled here at 5.4.1). LUCENE-6919 changed one line of BulkScorer.java, the cost() javadoc link, and left the example, whose block ends 12 lines above that link, as it was. Nothing runs the example, so no search result changes; the fix changes two lines: scorer.iterator().advance(min) and scorer.iterator().nextDoc().

// :48  "For instance, a {@link Scorer}-based implementation could look like below:"
private final Scorer scorer; // set via constructor

public int score(LeafCollector collector, Bits acceptDocs, int min, int max) throws IOException {
  collector.setScorer(scorer);
  int doc = scorer.docID();
  if (doc < min) {
    doc = scorer.advance(min);          // :57  Scorer has no advance(int)
  }
  while (doc < max) {
    if (acceptDocs == null || acceptDocs.get(doc)) {
      collector.collect(doc);
    }
    doc = scorer.nextDoc();             // :63  Scorer has no nextDoc()
  }
  return doc;
}

• What Scorer offers today. public abstract class Scorer extends Scorable (Scorer.java:28). Scorable has score(), smoothingScore(int), setMinCompetitiveScore(float) and getChildren(); Scorer adds docID() (:31) and iterator() (:43), among others, but no advance(int) and no nextDoc(). iterator() documents that "The returned iterator is a view: calling this method several times will return iterators that have the same state" (:40-41).
• Why it compiled once. At the 5.4.1 tag Scorer.java:42 reads public abstract class Scorer extends DocIdSetIterator; at the 5.5.0 tag it reads public abstract class Scorer, with public abstract DocIdSetIterator iterator() at :123. The example text is the same in both.
• How it was missed. LUCENE-6919 (ddb3a97678f) changed exactly one line of BulkScorer.java: {@link Scorer#cost()} became {@link DocIdSetIterator#cost()} in the cost() javadoc. The configured checks did not reject the example: doclint validates {@link} targets but does not compile code inside <pre>, and ErrorProne's InvalidSnippet check is about {@snippet} tags, which this block does not use (an intended-behaviour checker's reading of the build configuration, not a run).
• Nothing else depends on it. No other source under lucene/ calls scorer.advance(...) or scorer.nextDoc(); the only other text hit is a code comment in FunctionRangeQuery.java:155.

• Who. BulkScorer is public with no @lucene.internal or @lucene.experimental tag; it is what Weight#bulkScorer returns (Weight.java:170-178) through the public, overridable ScorerSupplier#bulkScorer() (ScorerSupplier.java:44). The class javadoc says only queries that "have a more optimized means of scoring across a range of documents need to override this" (BulkScorer.java:23-26), and the package docs call custom queries "an expert level task" (package-info.java:388-391). The audience is small and expert.
• Default vs opt-in. No runtime path: no Lucene code runs the example, and Lucene's own Scorer-backed bulk scorers use the iterator (Weight.java:240, :265-271; BatchScoreBulkScorer.java:45-46).
• Scale and age. Every release from 5.5.0 (released 2016-02-22) to 10.6.0, branch_10x and main. The failure is deterministic and loud: two javac errors that name the missing methods.
• What a reader loses. This is the only code in the score() javadoc that shows how to honour min, max and acceptDocs together, and it teaches an API shape (a Scorer that is its own iterator) that no longer exists.

• Faithful copy. A script compares the embedded block with the javadoc block at 645d4fe14a20 line for line (entities decoded): they match. Lines 14 and 20 of the compiled Example.java are the lines copied from BulkScorer.java:57 and :63.
• Assertions do not matter (it is a compile error); both modes were run and fail the same way.
• Releases. The same file fails unchanged on the 10.6.0, 10.5.2 and 9.12.3 release jars. Before 9.0 LuceneTestCase lives in org.apache.lucene.util; an equivalent verifier test with only that import changed fails on 5.5.0, 6.0.0 and 8.11.4 and passes on 5.4.1.
• As the regression test: this same method with the two corrected lines, in lucene/core/src/test/org/apache/lucene/search/. It guards a copy of the example, not the javadoc itself (it catches API drift, not a later edit of the block), so a reviewer may prefer no test for a javadoc-only change; and checkGoogleJavaFormat asks for two re-wraps in it (shown by the format check).

cp $REPRO/TestBulkScorerJavadocExample.java $LUCENE/lucene/core/src/test/org/apache/lucene/search/
cd $LUCENE
./gradlew :lucene:core:test --tests org.apache.lucene.search.TestBulkScorerJavadocExample -Ptests.seed=DEADBEEF -Ptests.asserts=true
# assertions off: -Ptests.asserts=false (same failure; the defect is at compile time)

# gradle, main 645d4fe14a20, seed DEADBEEF, -Ptests.asserts=true
TestBulkScorerJavadocExample > testScoreJavadocExampleCompiles FAILED
    java.lang.AssertionError: [/Example.java:14: error: cannot find symbol
        doc = scorer.advance(min);
                    ^
      symbol:   method advance(int)
      location: variable scorer of type org.apache.lucene.search.Scorer, /Example.java:20: error: cannot find symbol
        doc = scorer.nextDoc();
                    ^
      symbol:   method nextDoc()
      location: variable scorer of type org.apache.lucene.search.Scorer]
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:980D89C6B13FE5A5]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.assertTrue(Assert.java:42)
        at org.apache.lucene.search.TestBulkScorerJavadocExample.testScoreJavadocExampleCompiles(TestBulkScorerJavadocExample.java:75)
1 test completed, 1 failed
# -Ptests.asserts=false: the same two errors
# with fix A or B: BUILD SUCCESSFUL, 1 test

• The text presents it as an implementation. "For instance, a {@link Scorer}-based implementation could look like below:" (BulkScorer.java:48), then a <pre><code class="language-java"> block with real Lucene types and the exact signature of the abstract method (:53 vs :76).
• It was correct when written. LUCENE-6184 (#7246) added it on 2015-01-19 while Scorer extended DocIdSetIterator (trunk cb3ec682d41; the same-day branch_5x backport 5c9b5e7ea4e is the commit released in 5.1.0); LUCENE-6553 (#7611) added the acceptDocs lines (trunk d671dd8d890, branch_5x c00996c54a3, first in 5.3.0). Later edits are mechanical: 2d6ad2fee6d (reformatting, 2020) and 378ca8d1bbf (#15573, 2026-01-15, the <pre> wrapper only).
• The rest of Lucene teaches iterator(). Scorer's class javadoc ("A Scorer exposes an iterator() over documents"); the package docs (package-info.java:404-406, :473-475); BatchScoreBulkScorer.java:46; CHANGES.txt:9706-9708 records LUCENE-6919 as an API change in 5.5.0.
• Precedent. CHANGES.txt:11625 "LUCENE-6112: Fix compile error in FST package example code" (as the cross-model intended-lens review pointed out); 6fde1db2281 (#12693, Analyzer example); d1163450b6a (LUCENE-9046, TermInSetQuery example); 62f55c073c2 (LUCENE-8957, CustomAnalyzer examples).

Strongest case for "leave it" (a separate intended-behaviour checker and a cross-model reviewer, OpenAI GPT-5.6): "could look like below" marks an illustrative sketch; the block already omits its class, constructor and cost(); BulkScorer is an expert extension point most queries never implement, since the default bulk scorer does this job; Lucene does not compile javadoc snippets; and the error is loud, so nobody is misled at run time.

Why it fails: the omitted parts are the ones the reader is meant to supply (the comment says where the field comes from); the two broken lines are the core of what the example teaches and name methods that do not exist. It went stale by oversight in a commit that edited the same file, and upstream has fixed the same kind of example before. The cross-model lenses rated the argument weak; every verifier and the adjudication called it a real documentation defect.

Two validated options, both applied in a scratch worktree of main 645d4fe14a20 and run with gradle. Not in scope: compiling javadoc examples in the build (for example external, compiled {@snippet} sources), which would prevent the whole class of defect but is a tooling change discussed only generically upstream (#14257, #15225). Also out of scope: modernising the example; like the original, both fixes ignore Scorer#twoPhaseIterator() and LeafCollector#competitiveIterator(), which Weight.DefaultBulkScorer handles (Weight.java:238-243, :255).

Two changed lines in the BulkScorer#score javadoc example.

   *   if (doc < min) {
-  *     doc = scorer.advance(min);
+  *     doc = scorer.iterator().advance(min);
   *   }
   *   while (doc < max) {
   *     if (acceptDocs == null || acceptDocs.get(doc)) {
   *       collector.collect(doc);
   *     }
-  *     doc = scorer.nextDoc();
+  *     doc = scorer.iterator().nextDoc();
   *   }

Trade-offs

• The smallest change, and the same form as BatchScoreBulkScorer.java:46. In contract: Scorer#iterator() says repeated calls return views with the same state (Scorer.java:40-41).
• It calls iterator() once per document; fine for an example, while a real implementation would cache it, as option B and Weight.DefaultBulkScorer do.

What the checks validated

• Gradle, scratch worktree of 645d4fe14a20, seed DEADBEEF: the minimal test fails before the change and, with its example regenerated mechanically from the patched BulkScorer.java (byte-identical to the hunt's fix check), passes after it, with -Ptests.asserts=true and false.
• TestBooleanScorer (20 tests, covers the default bulk scorer) passes; :lucene:core:checkGoogleJavaFormat and :lucene:core:renderJavadoc pass on the patched file, and the rendered BulkScorer.html shows the two corrected calls.
• Semantics: the hunt unit's control runs the corrected example on a 20-doc index (window [4, 13) collects 6, 9, 12, then 15, 18 and NO_MORE_DOCS) with assertions on and off; a cross-model reviewer's own semantic test passed too.
• Not run: gradlew check or other modules (the change is inside a javadoc comment).

Four changed lines: DocIdSetIterator iterator = scorer.iterator(); after collector.setScorer(scorer);, then iterator.docID(), iterator.advance(min) and iterator.nextDoc().

   *   collector.setScorer(scorer);
-  *   int doc = scorer.docID();
+  *   DocIdSetIterator iterator = scorer.iterator();
+  *   int doc = iterator.docID();
   *   if (doc < min) {
-  *     doc = scorer.advance(min);
+  *     doc = iterator.advance(min);
   *   }
   ...
-  *     doc = scorer.nextDoc();
+  *     doc = iterator.nextDoc();

Trade-offs

Reads like Lucene's own Weight.DefaultBulkScorer (Weight.java:240, :265-271), which keeps the iterator instead of calling iterator() per document. A style choice, not a correctness one (an intended-behaviour checker and the adjudication said the same). The cross-model fact check of this doc preferred B: it mirrors DefaultBulkScorer, avoids an iterator() call on every pass and reads better as teaching code.

What the checks validated

Gradle, seed DEADBEEF: the minimal test regenerated from the patched javadoc passes with -Ptests.asserts=true and false. Not run for B: the format check, javadoc rendering and the semantic control.

• Lead. A first probe compiled javadoc code blocks against the stock main 645d4fe14a20 jars and got both errors (2026-10-29); a hunt unit re-ran it and extracted the block mechanically from the source.
• API scan. A java.lang.classfile scan of 159 core jars (1.9.1 to main) found Scorer.advance(int) and Scorer.nextDoc() in every build from 2.9.0 to 5.4.1 and in none from 5.5.0 on; javac cross-checked the boundary.
• Verification. An independent reproducer with its own test, cross-model lenses (OpenAI GPT-5.6, refute and intended), an intended-behaviour devil's advocate and an adjudication all called it real; an impact audit kept it as a Low documentation defect.