GIN versus zero-key queries

Our fine manual sayeth (in section 52.5)

When extractQuery returns zero keys, GIN will emit an error. Depending
on the operator, a void query might match all, some, or none of the
indexed values (for example, every array contains the empty array, but
does not overlap the empty array), and GIN cannot determine the correct
answer, nor produce a full-index-scan result if it could determine that
that was correct.

However, the behavior actually implemented by newScanKey() doesn't seem
to agree with this. If there are multiple scankeys (ie, multiple
indexable clauses) then what actually happens is you get an error
report only if *all* the clauses are zero-key queries. If some clauses
are zero-key and some are normal, it effectively ignores the zero-key
ones and sails ahead with the normal ones. This amounts to assuming
that the zero-key queries match all possible indexed values. But as
noted by the manual, that's not a correct conclusion for some operator
semantics.

I am not sure whether the statement in 52.5 is still accurate, though.
We have an API definition by which extractQuery can distinguish "all
match" from "no match". If we just legislate that "some match" isn't
a valid behavior for zero-key queries, then the code is correct and the
documentation is wrong. However, if the above quote is correct, then
I think newScanKey() is buggy.

Comments?

regards, tom lane