Re: create opclass documentation outdated

Julien Rouhaud <julien(dot)rouhaud(at)dalibo(dot)com> writes:
> On 25/02/2016 23:12, Vik Fearing wrote:
>> On 02/25/2016 09:13 PM, Julien Rouhaud wrote:
>>> I just saw that the CREATE OPERATOR CLASS documentation doesn't
>>> mention that BRIN indexes also support the STORAGE parameter.

>> I think this is the wrong approach; that parenthetical list now
>> represents a full 50% of the available AMs. I submit it should be
>> removed altogether.

> With further inspection, the "Interfacing Extensions To Indexes"
> (35.14) documentation also has a list of AMs supporting the STORAGE
> parameter. I believe having at least one page referencing which AMs
> support this parameter could be helpful for people who want to
> implement new opclass.

I think the problem here is more thoroughgoing, namely that neither
create_opclass.sgml nor xindex.sgml was touched at all for BRIN.

In create_opclass.sgml, not only do we have the list of AMs supporting
STORAGE, but there is also a paragraph describing which AMs do what
for input datatypes of FUNCTION members (around line 175).

xindex.sgml has that one list you mentioned, but there's not much
point in fixing that when BRIN indexes fail to be described either in
35.14.2 or 35.14.3, where they certainly should be. And there are
other places throughout that chapter that say that such-and-such AMs
support each feature as it's discussed.

I'm inclined to feel that the right answer is to fix all these
omissions, not to decide that we're not maintaining this documentation
anymore. Alvaro, I think this one's in your court.

regards, tom lane