Re: WIP: document the hook system

David Fetter <david(at)fetter(dot)org> writes:
> I'm -1 on making a README alone. These are public APIs, and as such,
> the fact of their existence shouldn't be a mystery discoverable only
> by knowing that there's something to look for in the source tree and
> then running an appropriate grep command to find the current ones

Meh. Almost always, effective use of a hook requires a substantial
amount of code-reading, so I don't have much use for the idea that
hook users shouldn't need to be familiar with how to find things in
the source tree. Now, you could argue "if we had a higher standard
of documentation for hooks, that wouldn't be necessary" ... to
which I'd reply "if we enforced such a standard of documentation,
there would be approximately zero hooks". Almost all the ones that
exist got in there partly because of the low overhead involved in
adding one.

Moreover, if by "public API" you mean something we're promising
to hold stable, then there won't be approximately zero hooks,
there will be *precisely* zero hooks. I can't think of any
interesting hook that isn't in a place where relevant APIs
change regularly. (I think the SPI entry points might be the
only backend-internal functions that we treat as stable APIs
in that sense.) The more documentation you expect to exist for
a hook, the more likely that some of it will be out of date.
This situation won't be helped any by our community's proven
track record of failing to update comments that are more than
three lines away from the code they're changing. (OK, I'm being
unduly negative here, perhaps. But this is a very real problem.)

I think that the best you should hope for here is that people are
willing to add a short, not-too-detailed para to a markup-free
plain-text README file that lists all the hooks. As soon as it
gets any more complex than that, either the doco aspect will be
ignored, or there simply won't be any more hooks.

(I'm afraid I likewise don't believe in the idea of carrying a test
module for each hook. Again, requiring that is a good way to
ensure that new hooks just won't happen.)

regards, tom lane