Re: WIP: document the hook system

On Fri, Feb 12, 2021 at 08:02:51PM +0300, Anastasia Lubennikova wrote:
> On 17.01.2021 16:53, Magnus Hagander wrote:
> > On Fri, Jan 15, 2021 at 8:28 AM Peter Eisentraut
> > <peter(dot)eisentraut(at)enterprisedb(dot)com> wrote:
> > > On 2020-12-31 04:28, David Fetter wrote:
> > > > This could probably use a lot of filling in, but having it in the
> > > > actual documentation beats needing to know folklore even to know
> > > > that the capability is there.
> > > This patch seems quite short of a state where one could begin to
> > > evaluate it. Documenting the hooks better seems a worthwhile goal. I
> > > think the question is whether we can develop documentation that is
> > > genuinely useful by itself without studying the relevant source code.
> > > This submission does not address that question.
> > Even just having a list of available hooks would be a nice improvement though :)
> >
> > But maybe it's something that belongs better in a README file instead,
> > since as you say it's unlikely to be properly useful without looking
> > at the source anyway. But just a list of hooks and a *very* high
> > overview of where each of them hooks in would definitely be useful to
> > have somewhere, I think. Having to find with "grep" whether there may
> > or may not exist a hook for approximately what it is you're looking
> > for is definitely a process to improve on.
> >
> +1 for README.
> Hooks are intended for developers and can be quite dangerous without proper
> understanding of the internal code.
>
> I also want to remind about a readme gathered by mentees [1]. It was done
> under a PostgreSQL license, so we can use it.
> By the way, is there any agreement on the plain-text format of PostrgeSQL
> README files or we can use md?
>
> [1] https://github.com/AmatanHead/psql-hooks/blob/master/Detailed.md

This is much more thorough than what I've done so far, and a much
better document in terms of pointing to actual hunks of the source for
context.

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

Would a document simply listing current hooks and pointing to
something along the lines of README_hooks in src work better?

Best,
David.
--
David Fetter <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778

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