Circle's javadoc example does not compile: LatLonShape.newDistanceQuery needs a QueryRelation

The class javadoc of org.apache.lucene.geo.Circle has one "Example usage" (Circle.java:37-45 on main 645d4fe14a20): a circle of 1 km around the Eiffel Tower, then Query query = LatLonShape.newDistanceQuery("location", circle); (:44). Copied into code, that line does not compile on any release that has the example (10.3.0 to 10.6.0) or on main. The only LatLonShape.newDistanceQuery is newDistanceQuery(String field, QueryRelation queryRelation, Circle... circle) (LatLonShape.java:316-319), which has needed a ShapeField.QueryRelation since LUCENE-8707 added it in 8.5.0; no two-argument form has ever existed, so the example, added by #14534 in 10.3.0, could not compile on the day it was written. With ShapeField.QueryRelation.INTERSECTS the call compiles and, of two points 500 m and 5 km from the centre, matches only the near one. No runtime code is wrong.

// Create a circle with 1km radius around the Eiffel Tower
Circle circle = new Circle(48.8584, 2.2945, 1000);

// Create a query using this circle
Query query = LatLonShape.newDistanceQuery("location", circle);

• LatLonShape.java:315-319: the only overload is public static Query newDistanceQuery(String field, QueryRelation queryRelation, Circle... circle), documented as "create a query to find all polygons that intersect a provided circle."
• Because the circles are varargs, a two-argument call has a matching arity (field, relation, zero circles), so javac tries to pass circle as the QueryRelation and reports incompatible types: Circle cannot be converted to QueryRelation at the query line (the test, which calls the compiler through javax.tools, prints the type names in full). A single non-varargs method with the same three parameters would get an arity error instead ("actual and formal argument lists differ in length"); -Xdiags:verbose confirms the mechanism: "required: String,QueryRelation,Circle[] found: String,Circle reason: argument mismatch".
• No (String, Circle) method exists anywhere: LatLonPoint.newDistanceQuery takes (String, double, double, double) (LatLonPoint.java:296-297), LatLonPoint.newGeometryQuery takes (String, ShapeField.QueryRelation, LatLonGeometry...) (:327-328), and XYShape.newDistanceQuery takes (String, QueryRelation, XYCircle...) (XYShape.java:252-253). A class-file scan of 159 core jars, 1.9.1 to main, finds no (String, Circle) overload in any build.
• ShapeField.QueryRelation (ShapeField.java:119-128) has the values INTERSECTS, WITHIN, DISJOINT and CONTAINS; INTERSECTS matches the method's own javadoc.

Nothing in the build compiles <pre>{@code} blocks. The build enables Error Prone's InvalidSnippet check, which covers @snippet tags only (an observation of the hunt's devil's-advocate verifier). The open issue #9534 (LUCENE-8488) asks for compile-checked javadoc examples in general.

The other code examples the same change added (Rectangle.java:53-60, geo/package-info.java:64-65) compile and run once Rectangle's free names lat, lon and radiusMeters are declared, so this is the one broken example in it.

• Who is hit. Anyone who copies the only code example in the Circle class javadoc to build a distance query on a LatLonShape field. Circle is @lucene.experimental (Circle.java:47).
• Default vs opt-in. Not a configuration matter: every copy fails, on every release that has the example (10.3.0 to 10.6.0) and on main.
• Scale. One line, one compile error. The message names ShapeField.QueryRelation, so a developer can recover from the method signature, but must then choose a relation the example does not explain: for indexed points INTERSECTS means "within 1 km", for lines and polygons "touches or overlaps the circle" (a point the hunt's refute reviewer made).
• What it does not do. No wrong results, no runtime path, no index change. LatLonShape's API is right; only the Circle example is wrong. (The method's one-line javadoc, "find all polygons that intersect a provided circle", describes only the INTERSECTS case; the method takes any QueryRelation.)

• The test compiles the two statements of Circle.java:41 and :44 verbatim with javax.tools, against java.class.path. Example.java:8 in the output is the example's query line, Circle.java:44.
• Even simpler for a reader: paste the two lines into any method, import LatLonShape, Circle and Query, and compile; javac prints the same error with short type names: incompatible types: Circle cannot be converted to QueryRelation.
• Results: fails 1 of 1 on main with assertions on and off, standalone (1.62 s) and through gradle, and on the published 10.6.0 and 10.3.0 jars. The hunt's and the verifiers' tests (the same call in larger tests) also fail on 10.5.2, the 10.6.0 RC1 and branch_10x 657014b3c579.
• 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 TestCircleJavadocExample.java $LUCENE/lucene/core/src/test/org/apache/lucene/geo/
cd $LUCENE && ./gradlew :lucene:core:test --tests org.apache.lucene.geo.TestCircleJavadocExample -Ptests.seed=DEADBEEF
# assertions off: add -Ptests.asserts=false (same result)

TestCircleJavadocExample > testClassJavadocExampleCompiles FAILED
    java.lang.AssertionError: [/Example.java:8: error: incompatible types: org.apache.lucene.geo.Circle cannot be converted to org.apache.lucene.document.ShapeField.QueryRelation
    Query query = LatLonShape.newDistanceQuery("location", circle);
                                                           ^, Note: Some messages have been simplified; recompile with -Xdiags:verbose to get full output]
        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.geo.TestCircleJavadocExample.testClassJavadocExampleCompiles(TestCircleJavadocExample.java:61)

• Contract text. Circle.java:37: "Example usage:". LatLonShape.java:316-317: newDistanceQuery(String field, QueryRelation queryRelation, Circle... circle). LatLonShape's class javadoc describes each query factory it lists (box, line, polygon and geometry queries) as matching shapes "that have some {@link QueryRelation}" with the geometry (LatLonShape.java:61-68), and every LatLonShape query factory, newDistanceQuery included, takes a QueryRelation (LatLonShape.java:239-326).
• History. LUCENE-8707 (d48bafb2999, apache/lucene-solr#587, Ignacio Vera, 2020-02-19; 8.5.0) added the method with this one signature. #14534 (bb8b1397b01, jainankitk, 2025-05-06; 10.3.0), "Improve user-facing docs for geo package", added the example; its one review (an approval by jpountz, "Great!") and its one comment (about the commit message) do not discuss it. The only later commit on the file, #15874 (2026-04-01), does not touch it.
• Precedent. #10088 (LUCENE-9046, "Fix wrong example in Javadoc of TermInSetQuery") and #12693 ("chore: update the Javadoc example in Analyzer", merged 2023-10-18) fixed wrong javadoc examples.
• Tests. No test compiles javadoc examples; #9534 (LUCENE-8488, open) asks for that in general.

Strongest case for "intended" (built by the intended-behaviour checks and the refute review): javadoc <pre>{@code} blocks are uncompiled sketches that also leave out imports; the explicit relation is a deliberate API choice, shared by XYShape and LatLonPoint.newGeometryQuery; Circle is @lucene.experimental; and the error is loud and names the missing type.

Why it fails: a reader can supply missing imports, but not a missing mandatory argument. The defect is the example, not the API. @lucene.experimental warns that the API may change incompatibly, not that its current docs may be wrong. Loud means low impact, not intended. Every verifier and the adjudication rejected the "intended" reading; it stays at Low because it is a wrong API call, not a typo.

Two ways to resolve it; A is the smallest and was validated. A' is the same fix with the nested type imported; B removes the call instead.

Backport: the same diff applies to the 10.6.0 Circle.java (checked with a patch dry run). Upstream retired branch_10x on 2026-10-29 (#16911; 10.6 is the last 10.x minor, and bug fixes may still go to branch_10_6), so the targets are main and branch_11x, plus branch_10_6 if wanted.

Change Circle.java:44 to Query query = LatLonShape.newDistanceQuery("location", ShapeField.QueryRelation.INTERSECTS, circle);. Javadoc only, 1 line changed.

--- a/lucene/core/src/java/org/apache/lucene/geo/Circle.java
+++ b/lucene/core/src/java/org/apache/lucene/geo/Circle.java
@@ -41,7 +41,7 @@
  * Circle circle = new Circle(48.8584, 2.2945, 1000);
  *
  * // Create a query using this circle
- * Query query = LatLonShape.newDistanceQuery("location", circle);
+ * Query query = LatLonShape.newDistanceQuery("location", ShapeField.QueryRelation.INTERSECTS, circle);
  * }</pre>
  *
  * @lucene.experimental

Trade-offs

• INTERSECTS matches the method's own javadoc ("find all polygons that intersect a provided circle", LatLonShape.java:315); for indexed points it means "within 1 km".
• The ShapeField.QueryRelation spelling matches LatLonPoint.newGeometryQuery's signature (LatLonPoint.java:328) and needs one more import, ShapeField, next to the imports the example already leaves to the reader. The adjudication and the cross-model reviews preferred it.
• The line is 103 characters wide in the source; wrap it after Query query = if you prefer 100 columns. The comment above it could also say what the query matches (not run; comment only).

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 (5 lines) to the text compiled by the same test, and that test passes with assertions on and off.
• Closest suites with the diff: TestCircle, TestCircle2D, TestLatLonShape: 3 classes, 37 tests, 0 failures (1 skipped: testRandomPolygons, ignored upstream).
• ./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 line.
• At runtime the corrected call matches 1 of 2 points (500 m in, 5 km out), with assertions on and off (the hunt's control). The full Lucene test suite was not run (javadoc-only change).

Write Query query = LatLonShape.newDistanceQuery("location", QueryRelation.INTERSECTS, circle); (the finder's diff).

Trade-offs

• Shorter (92 characters), as LatLonShape's own signature spells it.
• The reader must import the nested type org.apache.lucene.document.ShapeField.QueryRelation, which is less obvious than importing ShapeField.

What the checks validated

Compile-checked: the same one test with this line passes 1 of 1 on main (2026-10-29).

Keep only the new Circle(...) line and add, in prose, "use it with {@link org.apache.lucene.document.LatLonShape#newDistanceQuery}".

Trade-offs

• Less to keep in sync. It fits rmuir's comment on #15225 (2025-10-25): "Code examples need to be kept extremely minimal in the rare cases where it does make sense: the maintenance cost is very high and we don't have great validation for these."
• Loses the one worked call; mikemccand suggested on the same issue (2025-11-13) correcting "any code examples that are stale".

What the checks validated

Not run.

• A probe first compiled the block verbatim against the stock main 645d4fe14a20 jars and got the error (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.5.2, the 10.6.0 RC1, branch_10x and main) the example's API members exist, with a class-file scan whose boundaries were cross-checked with javac: the two-argument call exists in none.
• A helper that compiles each version's own javadoc block dated the defect: no example on 9.12.3 and 10.2.2, the error from 10.3.0 on.
• A corrected-call control on a real index matched exactly the point inside the circle, 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.