On Wed, Dec 28, 2016 at 01:33:13AM +0000, Tsunakawa, Takayuki wrote:
> 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: ...
> */
It's still new. For the record, I think it's an excellent idea.
I see it as larger in scope than mine because it changes how we do
things as a project. An example of the kind of thing that this raises
is enforcement. Will something (or someone) check that new hooks have
this? Will somebody check for comment skew when the APIs change?
What happens when somebody forgets?
> > 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 you meant
> adding a new chapter under the part "V. Server Programming".
Exactly :)
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
