Re: [PATCH][Documination] Add optional USING keyword before opclass name in INSERT statemet

Nikolay Shaplov <n(dot)shaplov(at)postgrespro(dot)ru> writes:
> If I read gram.y code for insert statement, I see that there is an optional
> USING keyword before opclass name

> opt_class: any_name { $$ = $1; }
> | USING any_name { $$ = $2; }
> | /*EMPTY*/ { $$ = NIL; }
> ;

> but it the documentation this keyword is omitted.

I think we should seriously consider fixing this code/docs discrepancy
by making the code match the docs, not vice versa. That is, let's just
remove the USING alternative here entirely.

If we wanted to make the docs match the code, it would not only be
CREATE INDEX that would have to be patched, because that's not the
only place that index_elem can appear. As far as I can find in a
quick search, none of the relevant statements have ever documented
that USING is allowed here; nor does it appear that any client-side
code of ours makes use of the keyword.

Also, because USING is already used elsewhere in CREATE INDEX (to
introduce the optional index AM name), I think that documenting its
use in this clause would add confusion not subtract it. References
to "the USING clause in CREATE INDEX" would become ambiguous.

This wouldn't be something to back-patch, of course, but I think it's
an entirely reasonable change to make in HEAD.

Comments?

regards, tom lane