David Fetter <david@fetter.org> writes:
> One of our hidden treasures is the hook system, documented only in
> random presentations, if you can find them, and in the source code, if
> you know to look.
> I'd like to document the hooks that we consider public APIs.
The main reason we send people to the source code for that is that
it's often not very clear what the extent of a hook's API is. It would
not be terribly useful to document, say, planner_hook just by listing
its arguments and result type. To do anything useful with that hook
requires a pretty extensive understanding of what the planner does,
and you're not going to get that without a willingness to read source.
So I'm a bit suspicious of this project in the first place, but it's
hard to discuss which hooks should be documented when you haven't
defined what you mean by documentation.
Anyway, there aren't any hooks that weren't put in with the expectation
of third-party code using them, so I'm not following your proposed
distinction between public and private hooks.
regards, tom lane