Re: [HACKERS] Hooks

On Wed, Dec 28, 2016 at 12:47:10AM +0000, Tsunakawa, Takayuki wrote:
> From: pgsql-hackers-owner@postgresql.org
> > [mailto:pgsql-hackers-owner@postgresql.org] On Behalf Of Jim Nasby
> > AFAIK there's no way to get a list of hooks today, short of
> > something like `git grep hook`. I think a simple list of what
> > hooks we have, when they fire and where to find them in code would
> > be sufficient.
> 
> How about putting a descriptive comment at the location where each
> hook variable is defined, using some convention (e.g. like
> Javadoc-style)?  A separate document such as README and wiki can
> fail to be updated.  OTOH, if someone wants to add a new hook, we
> can expect him to add appropriate comment by following existing
> hooks.  Using a fixed tag, e.g. "<Hook>", would facilitate finding
> all hooks.

I like this idea, but it's a much bigger one than mine because it's
essentially inventing (or adopting, whatever we settle on) literate
programming for the PostgreSQL project.

https://en.wikipedia.org/wiki/Literate_programming

In the realm of generated documentation, we do have a doxygen
https://doxygen.postgresql.org/ for the project, but I haven't really
found it helpful thus far.

Let's take up literate programming in a separate thread.

At the moment, our practice is that (most--hooks being an exception)
user-facing features must come with with user-facing docs which are
written separately from the source code implementing them.

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