Documentation: GiST extension implementation

Hi,

The following documentation page explains the GiST API to extensions authors:
http://www.postgresql.org/docs/current/static/gist-implementation.htm

I think we should be a little more verbose, and at least explains some more
the big picture: same/consistent/union are responsible for correctness of the
index while penalty and picksplit are responsible for performances of it,
which leaves compress/decompress, to use when leaf/nodes are not the same
datatype.

This leaf/node construct is explained in the last paragraph of following page,
but can exists directly into the C module too:
http://www.postgresql.org/docs/current/static/xindex.html

The consistent and union should get a lot of attention, and when exactly do
your operators need RECHECK is still unclear to me. It's hard to give precise
advices about consistent/union in a generic way, but I've been given the
following general rule (thanks RhodiumToad):
(z is consistent with x) implies (z is consistent with union(x,y))

What's unclear too is memory management: when to palloc() and when to reuse
arguments given by -core GiST support functions. I know it was a game of trial
and error to get it right, and while I know it's working now, I'd be in a bad
position to explain how and why. Maybe reading the source code is what to do
here, but a detailed API expectancies page in the documentation wouldn't
hurt...

Regards,
--
dim

I didn't propose a real doc patch mainly because english isn't my native
language, and while you'll have to reword the content...