LeafCollector's javadoc example does not compile: no scoreMode(), and setScorer(Scorer) instead of setScorer(Scorable)

The LeafCollector class javadoc explains that collect(int) receives segment-relative doc IDs and shows "a simple example showing how to collect docIDs into a BitSet" (LeafCollector.java:30-57 on main 645d4fe14a20). Copied into code, it does not compile on any release since 5.1.0: the anonymous Collector lacks the abstract scoreMode() (Collector.java:56; needsScores() from 5.1.0 to 7.x), and the anonymous LeafCollector declares setScorer(Scorer) (:46) where the interface, a few lines below, declares setScorer(Scorable) (:71), so the example's method is only an overload. The example compiled when it was written for 5.0.0; LUCENE-6218 (5.1.0), LUCENE-4100 and LUCENE-6228 (both 8.0.0) changed the API and did not update it. Adding scoreMode() returning ScoreMode.COMPLETE_NO_SCORES and taking a Scorable makes it compile, and the corrected example collects exactly the expected global doc IDs. No runtime code is wrong.

IndexSearcher searcher = new IndexSearcher(indexReader);
final BitSet bits = new BitSet(indexReader.maxDoc());
searcher.search(query, new Collector() {

  public LeafCollector getLeafCollector(LeafReaderContext context)
      throws IOException {
    final int docBase = context.docBase;
    return new LeafCollector() {

      // ignore scorer
      public void setScorer(Scorer scorer) throws IOException {
      }

      public void collect(int doc) throws IOException {
        bits.set(docBase + doc);
      }

    };
  }

});

1. No scoreMode(). The anonymous Collector implements only getLeafCollector (:40-54). Collector.java:56 declares ScoreMode scoreMode(); with no default (only setWeight has one, :63), so javac reports <anonymous Example$1> is not abstract and does not override abstract method scoreMode() in org.apache.lucene.search.Collector at searcher.search(query, new Collector() { (:38).
2. setScorer(Scorer) is an overload, not an override. The interface declares void setScorer(Scorable scorer) (:71). Scorer extends Scorable (Scorer.java:28), and a method with a narrower parameter type does not implement it, so javac reports <anonymous Example$1$1> is not abstract and does not override abstract method setScorer(org.apache.lucene.search.Scorable) in org.apache.lucene.search.LeafCollector at return new LeafCollector() { (:43). The other interface methods have defaults, and collect(int) is implemented.

The rest is valid: context.docBase is a public field (LeafReaderContext.java:28), and the deprecated IndexSearcher.search(Query, Collector) (IndexSearcher.java:634-638) still exists and only adds a deprecation note. indexReader and query are illustrative free names and not part of the claim.

The build's javadoc checks do not compile the code in this <pre> block. On main, the example's line 46 is the only setScorer(Scorer left in any .java file under lucene/, and the open issue #9534 (LUCENE-8488) asks for such a compile check in general.

• :31-32 "recording the docBase from the most recent setNextReader call": that method no longer exists; the example itself correctly reads context.docBase in getLeafCollector.
• :26 "hold onto the passed {@link Scorer} instance, and call {@link Scorer#score()}" and :68 "save the passed-in Scorer": the parameter is a Scorable.

• Who is hit. Anyone who writes a custom Collector from this example. It is the one worked example of doc-ID re-basing in the collector docs. Collector is marked Expert and both interfaces are @lucene.experimental (Collector.java:23, :44; LeafCollector.java:62), and the Collector javadoc steers most users to SimpleCollector or the built-in collectors (Collector.java:26-28).
• Default vs opt-in. Not a configuration matter: every copy fails. javac fails on each release compiled (5.1.0, 7.7.3, 8.0.0, 9.12.3, 10.5.2, 10.6.0, branch_10x and main), and a class-file scan finds the needed API members missing in all 109 builds from 5.1.0 to main.
• Scale. One example, 2 compile errors. LUCENE-9129 (#10170) shows a user hitting the same scoreMode() javac error in their own collector after upgrading from 7.x to 8.x, so the API change did trip up at least one user, although that report does not name the example.
• What it does not do. No wrong results, no runtime path, no index change. MIGRATE.md documents the Scorable change (lucene/MIGRATE.md:1474).

• The test compiles the 21 lines of LeafCollector.java:36-56 verbatim (only the <em> markup removed) with javax.tools, against java.class.path. Example.java:10 and :15 in the output are the example's lines 38 and 43. The deprecation note comes from the search(Query, Collector) call; it is a note, not an error.
• Even simpler for a reader: paste the 21 lines into any method that has an IndexReader indexReader and a Query query and compile; javac prints the same 2 errors.
• Results: fails 1 of 1 on main with assertions on and off, standalone (1.62 s) and through gradle; also fails on 10.6.0, 10.5.2, 9.12.3 and branch_10x 657014b3c579. Before 9.0 the test framework package differs, so the history runs on 5.0.0, 5.1.0, 7.7.3 and 8.0.0 used an import-only port.
• As a regression test: none is needed for a javadoc-only fix, and this test would not guard the javadoc anyway, because it compiles a copy of the text. The general guard is the tooling #9534 asks for.

cp TestLeafCollectorJavadocExample.java $LUCENE/lucene/core/src/test/org/apache/lucene/search/
cd $LUCENE && ./gradlew :lucene:core:test --tests org.apache.lucene.search.TestLeafCollectorJavadocExample -Ptests.seed=DEADBEEF
# assertions off: add -Ptests.asserts=false (same result)

TestLeafCollectorJavadocExample > testClassJavadocExampleCompiles FAILED
    java.lang.AssertionError: [/Example.java:10: error: <anonymous Example$1> is not abstract and does not override abstract method scoreMode() in org.apache.lucene.search.Collector
    searcher.search(query, new Collector() {
                                           ^, /Example.java:15: error: <anonymous Example$1$1> is not abstract and does not override abstract method setScorer(org.apache.lucene.search.Scorable) in org.apache.lucene.search.LeafCollector
        return new LeafCollector() {
                                   ^, Note: /Example.java uses or overrides a deprecated API., Note: Recompile with -Xlint:deprecation for details.]
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:9A7EBD6A0F12FB11]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.assertTrue(Assert.java:42)
        at org.apache.lucene.search.TestLeafCollectorJavadocExample.testClassJavadocExampleCompiles(TestLeafCollectorJavadocExample.java:81)

• Contract text. LeafCollector.java:32-33: "Here's a simple example showing how to collect docIDs into a BitSet:". :71: void setScorer(Scorable scorer) throws IOException;. Collector.java:55-56: "Indicates what features are required from the scorer." ScoreMode scoreMode(); (abstract).
• History. LUCENE-5527 (85642f59ddf, 2014) moved the example into LeafCollector; it compiles on 5.0.0 (executed). Earlier maintenance of the same example: 5f611724642 (2009, "The example impl in Collector missed the new method acceptsDocsOutOfOrder, added"), 647b5091697 (2012, "fix out of date api usage"), 927827a215a (2015, LUCENE-6179, removed acceptsDocsOutOfOrder()).
• API changes that skipped it. CHANGES.txt: "LUCENE-6218, LUCENE-6220: Add Collector.needsScores()" (lucene/CHANGES.txt:11080); MIGRATE.md: "LeafCollector.setScorer() now takes a Scorable rather than a Scorer (LUCENE-6228)" (lucene/MIGRATE.md:1474). The switch from needsScores() to scoreMode() (LUCENE-4100) has no MIGRATE entry and was listed only under "Optimizations" in the 8.0.0 CHANGES (as Tomoko Uchida pointed out on #10170). LUCENE-6228 (910a0231f6f) edited this very file and left the example.
• Tests. No test compiles javadoc examples; #9534 (LUCENE-8488, open) asks for that in general.

Strongest case for "intended" (verifiers built it): Collector is Expert and @lucene.experimental and points users to SimpleCollector; the snippet is a sketch (the free names indexReader and query); its entry point search(Query, Collector) is deprecated and slated for removal in 11.0 (#12892, listed in #16918; PR #16805 open); the errors are loud, CHANGES.txt lists the needsScores() addition and MIGRATE.md the Scorable change; the build does not compile javadoc <pre> blocks.

Why it fails: experimental status explains why the API changed, not why the same-version docs contradict the interface declared below them. The free names are context, while both errors are about missing API members. The deprecated call still compiles on every release. Maintainers updated this very example on earlier API moves. Every verifier and the adjudication rejected the "intended" reading; an impact audit passed it as a structurally wrong API example, not a typo.

Three ways to resolve it; A is the smallest and was validated. On main, open PR #16805 would remove the search(Query, Collector) call that A keeps; B is the variant that survives it.

Backport: on 10.6.0 and branch_10x the example code is the same, but the <pre> markup differs (#15573 changed it on main), so the diff's first hunk does not apply as is there; the same text edits apply by hand, and the second hunk applies (re-run by the independent fact check).

A committer may also prefer a SimpleCollector-based example: doSetNextReader receives the LeafReaderContext (SimpleCollector.java:36) and setScorer(Scorable) is already a no-op (:39-41). It still needs scoreMode(). Not run.

Add scoreMode() returning ScoreMode.COMPLETE_NO_SCORES to the anonymous Collector, take Scorable scorer in setScorer, and in the same javadoc replace "recording the docBase from the most recent setNextReader call" with "recording the docBase of the {@link org.apache.lucene.index.LeafReaderContext} passed to {@link Collector#getLeafCollector}", and "Scorer" with "Scorable" where the text describes the setScorer parameter (class javadoc and the setScorer method javadoc). Javadoc only: 13 lines added, 8 removed, formatted with ./gradlew tidy.

--- a/lucene/core/src/java/org/apache/lucene/search/LeafCollector.java
+++ b/lucene/core/src/java/org/apache/lucene/search/LeafCollector.java
  * searcher.search(query, new Collector() {
  *
+ *   public ScoreMode scoreMode() {
+ *     return ScoreMode.COMPLETE_NO_SCORES;
+ *   }
+ *
  *   public LeafCollector getLeafCollector(LeafReaderContext context)
@@
  *       <em>// ignore scorer</em>
- *       public void setScorer(Scorer scorer) throws IOException {
+ *       public void setScorer(Scorable scorer) throws IOException {
  *       }

Trade-offs

• COMPLETE_NO_SCORES is the honest mode: the example ignores scores and visits all matches ("Produced scorers will allow visiting all matches but scores won't be available", ScoreMode.java:25-26).
• Smallest change; keeps the example's shape and its lesson (re-basing with docBase).
• Keeps the deprecated search(Query, Collector) call: it compiles on branch_10x and on main today, but stops compiling if #16805 lands, so fix A on main would be short-lived. If #16805 is about to merge, B fits main and A fits branch_10x.

What the checks validated

• Gradle, scratch worktree of 645d4fe14a20, seed DEADBEEF, 2026-11-01: without the fix the repro fails with assertions on and off; with the diff, the patched example block is line-for-line identical (25 lines) to the corrected text compiled by the same test, and that test passes with assertions on and off.
• Closest core suites with the diff: TestMultiCollector, TestCollectorManager, TestTotalHitCountCollector, TestPositiveScoresOnlyCollector, TestCachingCollector: 5 classes, 22 tests, 0 failures.
• ./gradlew :lucene:core:check -x test passes (google-java-format, ecj lint, forbidden APIs, regeneration checksums; error-prone skipped), and ./gradlew :lucene:core:renderJavadoc passes with no warning lines in its log; the rendered page shows the corrected example.
• At runtime the corrected example collects {0, 3, 4, 5} on a 3-segment index (independent reproducer's control, main and 9.12.3). The full Lucene test suite was not run (javadoc-only change).

Replace the first three lines with final BitSet bits = new BitSet(indexReader.maxDoc()); and Collector collector = new Collector() {, keep the corrected body of A, and close with };.

 * final BitSet bits = new BitSet(indexReader.maxDoc());
 * Collector collector = new Collector() {
 *
 *   public ScoreMode scoreMode() {
 *     return ScoreMode.COMPLETE_NO_SCORES;
 *   }
 *   ... getLeafCollector exactly as in A ...
 * };

Trade-offs

• Uses no deprecated API, so it survives the removal of search(Query, Collector) (#12892, #16805).
• No longer shows how to run the collector; on main that is search(Query, CollectorManager), which needs per-collector state, more than this example should teach.

What the checks validated

Compile-checked: the same test with this text passes 1 of 1 on the stock main jars (2026-11-01). Not run at runtime.

Remove the <pre> block and refer readers to SimpleCollector and the built-in collectors, as the Collector javadoc already does.

Trade-offs

• Nothing left to drift.
• Loses the one worked illustration of docBase re-basing, which is the point of the paragraph.

What the checks validated

Not run (nothing to run).

• A first probe compiled the block verbatim against the stock main 645d4fe14a20 jars and got both errors (2026-10-29).
• The hunt unit re-ran it, extracted the block mechanically, wrote the one-test repro and checked in which of 159 core jars (every release from 1.9.1 to 10.6.0, branch_10x and main) the example's API members exist, with a class-file scan whose boundaries were cross-checked with javac: met only in 5.0.0, unmet from 5.1.0 on.
• Corrected-example controls compiled and collected exactly the global hit doc IDs over a 3-segment index, with assertions on and off, so only the text is wrong.
• This is a compile check of documentation code, not model checking or a proof.