Re: [HACKERS] Hooks

From: David Fetter [mailto:david@fetter.org]
> > 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

I didn't intend to invent a new heavy rule or tool.  I just meant comments just like the existing function
descriptions,something like
 

/** Hook name: Authentication hook* Description: ...* Arguments: ...* Return value: ...* Note: ...*/


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

Me, too.


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

OK.  Anyway, if we can see in the PostgreSQL documentation what hooks are available, it would be the best.  I imagine
youmeant adding a new chapter under the part "V. Server Programming".
 

Regards
Takayuki Tsunakawa