Re: Hooks

On Tue, Dec 27, 2016 at 01:32:46PM -0500, Tom Lane wrote:
> David Fetter <david(at)fetter(dot)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.

Indeed it wouldn't, but there are hooks where the API is, at least to
me, a little clearer, and I'll start with those.

> 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.

I would assume willingness to read source for anything hook related.
Documenting the hooks will help with places to look.

> 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.

I haven't quite come up with that, but I'd pictured a part of the SGML
docs that goes over, at a minimum, what all the hooks are and what
they do, at least at the level of a sentence or paragraph's worth of
description.

> 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.

That answers the question I had, which is essentially, "are there any
private hooks?" and the answer is no.

Best,
David.
--
David Fetter <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david(dot)fetter(at)gmail(dot)com

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate