BPIndexReorderer's javadoc usage example calls setForkJoinPool and a 2-argument reorder, both removed

BPIndexReorderer (lucene-misc) renumbers documents with recursive graph bisection so that similar documents sit together, which shrinks postings and can speed up queries. Its class javadoc, after describing the algorithm, says "Typical usage would look like this:" (line 73) and gives a 14-line example. Two of its lines name API that no longer exists: reorderer.setForkJoinPool(pool); (removed in 10.0.0) and reorderer.reorder(SlowCodecReaderWrapper.wrap(reader), targetDir) (the 2-argument form, removed in 9.12.0). The only public reorder is now reorder(CodecReader reader, Directory tempDir, Executor executor). Copied into a project, the two calls give cannot find symbol: method setForkJoinPool(java.util.concurrent.ForkJoinPool) and method reorder ... required: CodecReader,Directory,Executor; found: CodecReader,Directory on 10.0.0 to 10.6.0 and main, and the reorder error alone on 9.12.x. #13289 (2024-09-12) made both API changes and updated TestBPIndexReorderer to reorder(codecReader, dir, pool), but left the example. Passing the example's own pool as the third argument and deleting the setter line makes both calls compile; Lucene's 8 TestBPIndexReorderer tests pass with that javadoc change. Nothing in Lucene behaves wrongly; only the example is stale.

public CodecReader reorder(CodecReader reader, Directory tempDir, Executor executor) (line 838): "The provided Executor can be used to perform reordering concurrently. A value of null indicates that reordering should be performed in the current thread." and "The provided Executor must not reject tasks." A ForkJoinPool is an Executor, so the example's own pool fits the third argument unchanged. setForkJoinPool occurs nowhere under lucene/ except the javadoc line 83.

Javadoc does not compile <pre> code and no test reads the example. TestBPIndexReorderer calls reorder(codecReader, dir, pool) (lines 122, 184) and reorder(codecReader, dir, null) (line 307).

That the block as a whole "does not compile": reader is never initialised, targetPath is undeclared and targetDir is declared twice; those are placeholders. The claim is about the two API calls.

• Who. Readers of the BPIndexReorderer class javadoc who copy its example, its only class-level usage guide. No query, document or index file reaches it.
• Default vs opt-in. Opt-in: an expert, offline tool the application calls itself. No configuration or input changes the outcome: the copied calls always fail.
• Scale. 1 error on 9.12.0 to 9.12.3, 2 errors on 10.0.0 to 10.6.0 and main.
• Effect. A compile error, not wrong behaviour. The 9.12.x deprecation note on setForkJoinPool pointed to the 3-argument reorder; it went with the method in 10.0.0.
• Priority. Low; the same kind of defect as the other stale javadoc examples of the same sweep.

The two calls in the test were checked mechanically against BPIndexReorderer.java:83 and :85 at 645d4fe14a20: they are verbatim. /Example.java:10 and :11 in the output are those two lines.

Inside a Lucene checkout with gradle (./gradlew :lucene:misc:test --tests org.apache.lucene.misc.index.TestBPIndexReordererJavadocExample), the test as written fails for a class-path reason ("package org.apache.lucene.index does not exist"): Lucene's gradle test task runs lucene-core from the module path, which java.class.path does not include. Adding System.getProperty("jdk.module.path") to javac's -classpath fixes that; it then reports exactly the two errors below under gradle too (checked; the fixed twin passes under gradle).

No separate regression test is suggested: this test copies the example's calls, so it would not notice a later edit of the javadoc, and Lucene has no harness that compiles javadoc examples. TestBPIndexReorderer already exercises the 3-argument call with a pool.

# the command above, main 645d4fe14a20, seed DEADBEEF, -ea (-da identical); header lines (JUnit banner, vectorization warning, NOTE lines, Time: 1.86) left out, ... = remaining runner frames
There was 1 failure:
1) testClassJavadocExampleCalls(org.apache.lucene.misc.index.TestBPIndexReordererJavadocExample)
java.lang.AssertionError: javac errors: [/Example.java:10: error: cannot find symbol
    reorderer.setForkJoinPool(pool);
             ^
  symbol:   method setForkJoinPool(java.util.concurrent.ForkJoinPool)
  location: variable reorderer of type org.apache.lucene.misc.index.BPIndexReorderer, /Example.java:11: error: method reorder in class org.apache.lucene.misc.index.BPIndexReorderer cannot be applied to given types;
    return reorderer.reorder(SlowCodecReaderWrapper.wrap(reader), targetDir);
                    ^
  required: org.apache.lucene.index.CodecReader,org.apache.lucene.store.Directory,java.util.concurrent.Executor
  found:    org.apache.lucene.index.CodecReader,org.apache.lucene.store.Directory
  reason: actual and formal argument lists differ in length]
	at __randomizedtesting.SeedInfo.seed([DEADBEEF:6C73A58A0D93465A]:0)
	at org.junit.Assert.fail(Assert.java:89)
	at org.junit.Assert.assertTrue(Assert.java:42)
	at org.apache.lucene.misc.index.TestBPIndexReordererJavadocExample.testClassJavadocExampleCalls(TestBPIndexReordererJavadocExample.java:63)
	...
FAILURES!!!
Tests run: 1,  Failures: 1

# 10.6.0 and 10.0.0 release jars, -da: the same 2 errors; 9.12.0: only the reorder error (plus javac's deprecation note); 9.11.1: passes

• Offered as working code. "Typical usage would look like this:" (line 73), with no pseudo-code marker.
• Maintained as real code. #12568 (36432fa6724, 2023-09-19) replaced setForkJoinPool(ForkJoinPool.commonPool()) with the custom-factory pool, and 1d0edd76a5e ("Fix compilation under Java 11.", the same day) escaped the lambda's -> in it as -> (the Java 11 problem of that day's dev@ thread) and replaced a test-only random().nextBoolean() with false.
• The API change forgot it. #13289 (ff8b81afc59, Adrien Grand, 2024-09-12) removed setForkJoinPool on main (deprecated it on branch_9x: "Pass an executor to reorder(CodecReader, Directory, Executor) instead") and gave reorder the Executor argument. It updated TestBPIndexReorderer from setForkJoinPool(pool) + reorder(codecReader, dir) to reorder(codecReader, dir, pool); none of its hunks touches the class javadoc, and its discussion never mentions it.
• Public API. The class is public, in an exported package, with no @lucene.experimental or @lucene.internal tag.
• Precedent. LUCENE-9046 "Fix wrong example in Javadoc of TermInSetQuery"; #12693 "chore: update the Javadoc example in Analyzer" (2023-10-18); LUCENE-7763 removed an outdated javadoc comment (LUCENE-9046 and LUCENE-7763 were found by the cross-model reviewer, OpenAI GPT-5.6).

Strongest case for "not a bug": the block is illustrative pseudo-code. It never compiled as written (reader uninitialised, targetPath undeclared, targetDir declared twice), Lucene does not compile javadoc snippets, lucene-misc changes freely, the error is loud and the method javadoc is right.

Why it fails: it explains the placeholders, not two exact method calls. A reader supplies reader and targetPath; no context makes a removed method compile. The calls were edited as real code, compiled verbatim until 9.11.1, and broke only because #13289 changed the API without touching the example. The verifiers and the adjudication called it real (the refute lens could not run anything; its "not real" is procedural); the adjudication rated it a Low documentation defect.

One fix was validated, with the javadoc diff applied to 645d4fe14a20; the optional extras were not run.

Javadoc only, lucene/misc/src/java/org/apache/lucene/misc/index/BPIndexReorderer.java:83 and :85. A narrow API-drift fix: it makes the two calls compile, while the block keeps its placeholders (reader, targetPath, the duplicate targetDir, no imports), so it is still not a self-contained compilation unit.

- * reorderer.setForkJoinPool(pool);
  * reorderer.setFields(Collections.singleton("body"));
- * CodecReader reorderedReaderView = reorderer.reorder(SlowCodecReaderWrapper.wrap(reader), targetDir);
+ * CodecReader reorderedReaderView = reorderer.reorder(SlowCodecReaderWrapper.wrap(reader), targetDir, pool);

Trade-offs

None for users: documentation only. It keeps the pool as written (the devil's-advocate verifier's point); its custom thread factory came from #12568 ("Fix issues with BP tests and the security manager."), and whether the example still needs it is a separate question. reorder needs an Executor that does not reject tasks (line 834), which a live ForkJoinPool satisfies; the example never shuts the pool down (the devil's-advocate verifier's run did), and a pool.shutdown() after use would be optional polish (not run).

What the checks validated

• The minimal test with its two calls taken mechanically from the patched javadoc passes 1 of 1: plain javac/java on main with assertions on and off, standalone on main (on and off) and on the 10.6.0 jars, and under ./gradlew :lucene:misc:test (gradle form). The stock calls fail the same test, so it detects the bug.
• ./gradlew :lucene:misc:test --tests org.apache.lucene.misc.index.TestBPIndexReorderer -Ptests.seed=DEADBEEF: 8 tests, 0 failures.
• ./gradlew :lucene:misc:checkGoogleJavaFormat and :lucene:misc:renderJavadoc pass; the rendered class page shows the 3-argument call and no setForkJoinPool.
• At runtime, the devil's-advocate verifier ran the corrected calls on a real 200-document index on an earlier main with the same file: addIndexes and DirectoryReader.open succeed and all 200 ids survive.

Replace line 77 Directory targetDir; // Directory where to write the reordered index with Path targetPath; // where to write the reordered index: this removes the duplicate targetDir declaration and declares targetPath in one line.

Trade-offs

The adjudication's fix sketch includes removing the duplicate Directory targetDir; line, as a side nit the claim does not rest on.

The parameter is tempDir; the example passes targetDir, which works but may surprise. reorder writes its temporary files through a TrackingDirectoryWrapper over that directory (line 850) and deletes them before it returns (line 896; line 900 on failure). A short trailing comment, or a separate temporary directory, would make the contract explicit.

Trade-offs

Documentation only; no behaviour change.

• Sweep. A hunt unit for javadoc examples (siblings of another contributor's fix #16904) compiled every <pre><code class="language-java"> block of the non-sandbox lucene/**/src/java files with javax.tools against the stock main jars and flagged this block (2026-10-28).
• Targeted test. A public-API JUnit compiled the block verbatim, declaring only the undeclared name targetPath and counting only API-level errors; it found both errors and the version split.
• Tier. Non-formal: it compiles documentation code.