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.eisentr...@enterprisedb.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
