[
https://issues.apache.org/jira/browse/LUCENE-4040?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13271339#comment-13271339
]
Mike Sokolov commented on LUCENE-4040:
--------------------------------------
There is a real need for this. The surround parser in particular is very
poorly documented. There are some quirks that aren't at all apparent, like:
distance has a max of 99, and when distance > 99, you actually get a generic
syntax error because only two digits are allowed in the token. Also: the
default distance is one, but 1 is actually not allowed as an explicit distance
- you can only specify it implicitly. Finally the distance is off-by-one from
the slop parameter in the Span queries it ultimately generates. Distance of 0
in Spans == distance of 1 in the surround query syntax. And aside from all of
these specific issues, there is just a general lack of any sort of general
statement about what the allowable syntax is. The best documentation is the
javacc source, of course, but that's a bit unapproachable for a lot of folks
that might actually use this, I think.
> Improve QueryParser and supported syntax documentation
> ------------------------------------------------------
>
> Key: LUCENE-4040
> URL: https://issues.apache.org/jira/browse/LUCENE-4040
> Project: Lucene - Java
> Issue Type: Improvement
> Components: modules/queryparser
> Reporter: Chris Male
> Priority: Minor
>
> In LUCENE-4024 there were some changes to the fuzzy query syntax. Only the
> Classic QueryParser really documents its syntax, which makes it hard to know
> whether the changes effected other QPs. Compounding this issue there are
> many classes which have no javadocs at all and I found myself quite confused
> when I consolidated all the QPs into their module.
> We should do a concerted effort to improve the documentation so that it is
> clear what syntax is supported by what QPs and so that at least the user
> facing classes have javadocs.
> As part of this, I wonder whether we should give the syntax supported by the
> Classic QueryParser a new name (rather than just Lucene's query syntax) since
> other QPs can and do support other syntax, and then somehow add some typed
> control over this, so QPs have to declare programmatically that they support
> the syntax and so we can verify that by randomly plugging in implementations
> into tests.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
