MemoryIndex's javadoc example calls new SimpleAnalyzer(version) and new QueryParser(version, ...), constructors removed in 5.0.0, so it does not compile

MemoryIndex is Lucene's one-document, in-memory index, often used to check whether a single text matches a query. Its class javadoc has one end-to-end "Example Usage" program: build a SimpleAnalyzer, add a "content" and an "author" field, parse +author:james +salmon~ +fish* manual~ with the classic QueryParser and print "it's a match". The program's first line is new SimpleAnalyzer(version) and its fifth is new QueryParser(version, "content", analyzer). LUCENE-5859 removed both Version-taking constructors (trunk 2014; released in 5.0.0 through the branch_5x backport) and left this example, so it has not compiled on any release since 5.0.0: with the Lucene imports, both calls pass the wrong number of arguments, whatever version is declared as. With the two version arguments dropped it compiles and prints "it's a match" on main and 10.5.2. Documentation only: no code is wrong and nothing wrong ever runs.

MemoryIndex.java:144 opens "Example Usage"; the program is :147-158 inside <pre><code> (:146, :159):

Analyzer analyzer = new SimpleAnalyzer(version);                       // MemoryIndex.java:147
MemoryIndex index = new MemoryIndex();
index.addField("content", "Readings about Salmons and other select Alaska fishing Manuals", analyzer);
index.addField("author", "Tales of James", analyzer);
QueryParser parser = new QueryParser(version, "content", analyzer);    // MemoryIndex.java:151
float score = index.search(parser.parse("+author:james +salmon~ +fish* manual~"));
if (score > 0.0f) {
    System.out.println("it's a match");
} else {
    System.out.println("no match found");
}
System.out.println("indexData=" + index.toString());

• SimpleAnalyzer.java:32: public SimpleAnalyzer() {} is the only constructor.
• QueryParser.java:91 (classic): public QueryParser(String f, Analyzer a); the other two constructors are protected and take one argument (QueryParser(CharStream) :921, QueryParser(QueryParserTokenManager) :943).
• The two errors are about the number of arguments, so with the Lucene imports no declaration of version makes the calls compile.
• Nothing in the build checks it: code inside javadoc <pre> blocks is not compiled, and no {@snippet} is used anywhere under lucene/.

1. 2012-09-12: Robert Muir's "code snippet improvements: fix out of date api usage and add syntax highlighting" (647b5091697 trunk, d8d5bf5e07d branch_4x) wrote both calls in their current form. They were valid; first release 4.0.0.
2. 2014-08-08: LUCENE-5859 (9938a39a872, Ryan Ernst, "Remove Version from Analyzer constructors") removed SimpleAnalyzer(Version) and QueryParser(Version, String, Analyzer). In the memory module it changed only MemoryIndexTest.java (new QueryParser(TEST_VERSION_CURRENT, "foo", analyzer) became new QueryParser("foo", analyzer)), not MemoryIndex.java.
3. On branch_4x (cb9beac7079, 4.10.0) the two constructors were only deprecated, so 4.10.x still compiles the example. The branch_5x backport 55594bad9b0 (LUCENE-5944, 2014-09-18) carried the removal into 5.0.0.
4. Later commits (2014-2015 doclint fixes, LUCENE-9570 reformatting in 2021, #15573 in 2026) changed only the markup around the block.

• Who. Readers of the MemoryIndex class javadoc, the class's only end-to-end usage example. MemoryIndex is public and not marked @lucene.experimental; the highlighter (WeightedSpanTermExtractor, MemoryIndexOffsetStrategy) and the monitor (DocumentBatch) build on it. Users do quote this example: a 2016 java-user thread copies its addField lines.
• What they get. Two javac errors, on every release from 5.0.0 to 10.6.0 and on main.
• What they do not get. Any runtime effect: no wrong result, no exception at run time. javac names the valid constructors (SimpleAnalyzer(), QueryParser(String, Analyzer)), so the fix is quick once seen.
• Priority. Low; likelihood "plausible" (anyone who copies the example hits it, every time).

The test passes the example as a string to javax.tools and asserts that it compiles; on failure the message is javac's own diagnostics. The 12 lines are MemoryIndex.java:147-158 with > decoded; a script checked them against the javadoc line for line. Single thread, public API only. The test shows that the two calls fail with the intended Lucene imports and this ordinary wrapper; it does not test the bare fragment, which needs some such wrapper on every version, 4.10.4 included.

It sits in lucene/monitor because the memory module's own tests have no analysis-common (for SimpleAnalyzer). The javac class path includes the module path, which gradle uses for Lucene's modules. The same file also fails against the 10.6.0, 10.5.2 and 9.12.3 release jars.

Regression test (optional): this same test with the two fixed lines. It guards the documented calls; it cannot notice a later edit of the javadoc itself, since Lucene does not compile javadoc code.

cp $REPRO/TestMemoryIndexJavadocExample.java $LUCENE/lucene/monitor/src/test/org/apache/lucene/monitor/
cd $LUCENE
./gradlew :lucene:monitor:test --tests org.apache.lucene.monitor.TestMemoryIndexJavadocExample -Ptests.seed=DEADBEEF
# assertions off: add -Ptests.asserts=false (same failure)

# gradle, main 645d4fe14a20, seed DEADBEEF, assertions on (off: the same two errors)
TestMemoryIndexJavadocExample > testClassJavadocExampleCompiles FAILED
    java.lang.AssertionError: [/Example.java:8: error: constructor SimpleAnalyzer in class org.apache.lucene.analysis.core.SimpleAnalyzer cannot be applied to given types;
    Analyzer analyzer = new SimpleAnalyzer(version);
                        ^
      required: no arguments
      found:    org.apache.lucene.util.Version
      reason: actual and formal argument lists differ in length, /Example.java:12: error: no suitable constructor found for QueryParser(org.apache.lucene.util.Version,java.lang.String,org.apache.lucene.analysis.Analyzer)
    QueryParser parser = new QueryParser(version, "content", analyzer);
                         ^
        constructor org.apache.lucene.queryparser.classic.QueryParser.QueryParser(java.lang.String,org.apache.lucene.analysis.Analyzer) is not applicable
          (actual and formal argument lists differ in length)
        constructor org.apache.lucene.queryparser.classic.QueryParser.QueryParser(org.apache.lucene.queryparser.charstream.CharStream) is not applicable
          (actual and formal argument lists differ in length)
        constructor org.apache.lucene.queryparser.classic.QueryParser.QueryParser(org.apache.lucene.queryparser.classic.QueryParserTokenManager) is not applicable
          (actual and formal argument lists differ in length)]
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:9A7EBD6A0F12FB11]:0)
1 test completed, 1 failed

# Example.java:8 and :12 are lines 1 and 5 of the block (MemoryIndex.java:147 and :151)
# with the fix and the fixed text in the test: BUILD SUCCESSFUL, 1 test (assertions on and off)

• Meant to track the API. 647b5091697 / d8d5bf5e07d (Robert Muir, 2012-09-12), "code snippet improvements: fix out of date api usage and add syntax highlighting", wrote today's text. 4.10.4 compiles it.
• An oversight, not a decision. 9938a39a872 (LUCENE-5859) touched MemoryIndexTest.java but not MemoryIndex.java; the 55 comments of #6921 never mention MemoryIndex; MIGRATE.md and CHANGES.txt say nothing about keeping the example.
• Precedent. #12666 (the Analyzer class-doc example "does not work") was closed by #12693, "chore: update the Javadoc example in Analyzer" (2023); CHANGES.txt: "LUCENE-9046: Fix wrong example in Javadoc of TermInSetQuery".
• Not a placeholder. version is undeclared, which a reader can fill in; but with the Lucene imports no declaration of version fixes a call to a constructor that does not exist.
• What a reader can expect. Lucene does not compile javadoc code, so nothing guarantees that this block compiles. The claim is what a reader reasonably expects of an "Example Usage" block: that, with the imports added and version declared, it calls API that exists.

The case for "intended": the block is an uncompiled illustrative fragment (no imports, version never declared, no snippet tooling in the build) inside a class javadoc full of 2005-2006 prose (the Nux XQuery example, dead today.java.net links); the error is loud and names the right constructors; and a maintainer edited this exact block in January 2026 (#15573) without touching the calls.

Why it fails: #15573 ("Replace prettyprint with code tag for prism") changed 252 files mechanically, as the 2014-2015 doclint and 2021 reformatting commits also changed only the markup. With the Lucene imports no declaration of version makes the calls compile: they name API that does not exist. Every reviewer, including two from another model family (OpenAI GPT-5.6), and the adjudication rejected the argument. What remains true is that the impact is small, which is why it is Low.

One fix was validated with gradle in a scratch worktree of 645d4fe14a20; the alternatives were not run.

Exactly the change LUCENE-5859 made to the memory module's test. The example then uses the current constructors and no longer needs the undeclared version at all. 1 file, +2/-2, javadoc only.

--- a/lucene/memory/src/java/org/apache/lucene/index/memory/MemoryIndex.java
+++ b/lucene/memory/src/java/org/apache/lucene/index/memory/MemoryIndex.java
@@ -144,11 +144,11 @@
  * <p><b>Example Usage</b> <br>
  *
  * <pre><code class="language-java">
- * Analyzer analyzer = new SimpleAnalyzer(version);
+ * Analyzer analyzer = new SimpleAnalyzer();
  * MemoryIndex index = new MemoryIndex();
  * index.addField("content", "Readings about Salmons and other select Alaska fishing Manuals", analyzer);
  * index.addField("author", "Tales of James", analyzer);
- * QueryParser parser = new QueryParser(version, "content", analyzer);
+ * QueryParser parser = new QueryParser("content", analyzer);
  * float score = index.search(parser.parse("+author:james +salmon~ +fish* manual~"));
  * if (score &gt; 0.0f) {
  *     System.out.println("it's a match");

Trade-offs

• No behaviour, API or test change; trivially reviewable.
• Leaves the rest of the 2005-2006 prose (dead links, the XQuery block, JDK 1.5 profiling advice) alone.

What the checks validated

• Scratch worktree of 645d4fe14a20, gradle --offline, OpenJDK 25.0.3, seed DEADBEEF; the test in the monitor module's tests.
• Stock: the one-test repro fails with assertions on and off (both javac errors).
• With the diff: a script confirmed the patched javadoc block equals the fixed text line for line; the test with that text passes with assertions on and off.
• :lucene:memory:test, the whole module: 51 tests (TestMemoryIndex 30, TestMemoryIndexAgainstDirectory 16, TestSlicedIntBlockPool 5), 0 failures, 0 skipped.
• :lucene:memory:renderJavadoc, checkGoogleJavaFormat and ecjLintMain pass; with the test file in place, :lucene:monitor:checkGoogleJavaFormat, ecjLintTest and forbiddenApisTest pass.
• Earlier runs: the corrected example runs and prints "it's a match" (score 1.3487055) on main with -ea and -da and on 10.5.2; the cross-model reviewer ran 46 existing MemoryIndex tests against the patched source, all passing.
• Not run: the whole :lucene:monitor:test or ./gradlew check.

Add the five import lines so the block can be pasted as is. More text in a class javadoc, and other Lucene examples omit imports too; not needed to fix the defect.

Trade-offs

Longer example; same compile check as the recommended option.

What the checks validated

Not run.

Move examples to {@snippet} with compiled source files, or compile <pre> blocks in a build check. The only thing that would stop this class of drift.

Trade-offs

A build-tooling change far beyond a two-line docs fix; out of scope here.

What the checks validated

Not run.

• Lead. A first pass over javadoc examples compiled the block against the stock main jars and got both constructor errors.
• Hunt. The finder re-ran the lead, extracted the block mechanically from the source, and checked with a java.lang.classfile scan in which of 158 builds (every cached release 1.9.1-10.5.2, the 10.6.0 release candidate and main) the example's API members exist; the boundaries were cross-checked by compiling each release's own javadoc text with javac. It then wrote the one-test repro.
• Tier. Non-formal: compiling documentation code and scanning jars for API members, not a check against exact semantics.