hidingmyname opened a new issue, #16935:
URL: https://github.com/apache/lucene/issues/16935
### Description
### Summary
The javadoc on `DistanceSubQuery.distanceSubQueryNotAllowed()` says that when
it returns null, "addSpanNearQueries() can be used". The interface has no
`addSpanNearQueries()`. The method it means is declared right below it:
`addSpanQueries(SpanNearClauseFactory)`.
### Where
`lucene/queryparser/src/java/org/apache/lucene/queryparser/surround/query/DistanceSubQuery.java:21-32`:
```java
/** Interface for queries that can be nested as subqueries into a span near.
*/
public interface DistanceSubQuery {
/**
* When distanceSubQueryNotAllowed() returns non null, the reason why the
subquery is not allowed
* as a distance subquery is returned. <br>
* When distanceSubQueryNotAllowed() returns null addSpanNearQueries() can
be used in the creation
* of the span near clause for the subquery.
*/
String distanceSubQueryNotAllowed();
void addSpanQueries(SpanNearClauseFactory sncf) throws IOException;
}
```
All three implementations (`DistanceQuery`, `OrQuery`, `SimpleTerm`)
implement
`addSpanQueries`. The only match for `addSpanNearQueries` on `main` is this
comment.
### Why it matters
To be upfront about scope: the surround query parser is a niche module, and
this is a small fix.
This javadoc is the only documentation of the contract between the two
methods. You call `distanceSubQueryNotAllowed()` first, and only if it
returns
null do you call the other method. `addSpanQueries` has no javadoc of its
own,
so the second half of that contract points at a name that doesn't exist.
Anyone implementing `DistanceSubQuery` for a new surround node type has to
guess that it means the method below. Changing it to a `{@link}` lets javadoc
catch this if the method is ever renamed again.
### Suggested fix
```diff
/**
- * When distanceSubQueryNotAllowed() returns non null, the reason why the
subquery is not allowed
- * as a distance subquery is returned. <br>
- * When distanceSubQueryNotAllowed() returns null addSpanNearQueries()
can be used in the creation
- * of the span near clause for the subquery.
+ * When distanceSubQueryNotAllowed() returns non null, the reason why the
subquery is not allowed
+ * as a distance subquery is returned. <br>
+ * When distanceSubQueryNotAllowed() returns null {@link
#addSpanQueries(SpanNearClauseFactory)}
+ * can be used in the creation of the span near clause for the subquery.
*/
String distanceSubQueryNotAllowed();
```
(A plain-text `addSpanQueries()` would be the minimal version.)
### Upstream reference
Lucene.NET fixed this in its port in apache/lucenenet@`ced03f598`
("QueryParser: Fixed documentation comments"):
```diff
--- a/src/Lucene.Net.QueryParser/Surround/Query/DistanceSubQuery.cs
+++ b/src/Lucene.Net.QueryParser/Surround/Query/DistanceSubQuery.cs
/// <summary>
- /// When distanceSubQueryNotAllowed() returns non null, the reason
why the subquery
+ /// When <see cref="DistanceSubQueryNotAllowed()"/> returns non
null, the reason why the subquery
/// is not allowed as a distance subquery is returned.
- /// <br>When distanceSubQueryNotAllowed() returns null
addSpanNearQueries() can be used
+ /// <para/>When <see cref="DistanceSubQueryNotAllowed()"/> returns
null <see cref="AddSpanQueries(SpanNearClauseFactory)"/> can be used
/// in the creation of the span near clause for the subquery.
/// </summary>
string DistanceSubQueryNotAllowed();
```
Current Lucene.NET:
```csharp
/// <summary>
/// When <see cref="DistanceSubQueryNotAllowed()"/> returns non
null, the reason why the subquery
/// is not allowed as a distance subquery is returned.
/// <para/>When <see cref="DistanceSubQueryNotAllowed()"/> returns
null <see cref="AddSpanQueries(SpanNearClauseFactory)"/> can be used
/// in the creation of the span near clause for the subquery.
/// </summary>
string DistanceSubQueryNotAllowed();
void AddSpanQueries(SpanNearClauseFactory sncf);
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
