Re: Improve PQauthDataHook_type docs

On Sun, Apr 19, 2026 at 04:54:02PM +0100, Daniele Varrazzo wrote:
> Hello,
>
> In https://www.postgresql.org/docs/18/libpq-oauth.html#LIBPQ-OAUTH-AUTHDATA-HOOKS
> it is not entirely clear that `hook_fn` is the definition of the
> `PQauthDataHook_type` used in the functions signature, because the
> name is not used elsewhere. The function signatures refer to the
> typedef but the typedef is not shown.
>
> Using https://www.postgresql.org/docs/18/libpq-notice-processing.html#LIBPQ-NOTICE-PROCESSING
> as a guideline I suggest to show the typedef of the callback rather
> than the `hook_fn` example, so that the `PQauthDataHook_type` name can
> be searched for.
>
> Please check the patch attached.

> Use the typedef name to make it easier to correlate to the functions
> using this type definition.
> ---
> doc/src/sgml/libpq.sgml | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
> index e50f0cbd8c7..f646244840d 100644
> --- a/doc/src/sgml/libpq.sgml
> +++ b/doc/src/sgml/libpq.sgml
> @@ -10280,7 +10280,7 @@ void PQsetAuthDataHook(PQauthDataHook_type hook);
> default handler will be reinstalled. Otherwise, the application passes
> a pointer to a callback function with the signature:
> <programlisting>
> -int hook_fn(PGauthData type, PGconn *conn, void *data);
> +typedef int (*PQauthDataHook_type) (PGauthData type, PGconn *conn, void *data);
> </programlisting>
> which <application>libpq</application> will call when an action is
> required of the application. <replaceable>type</replaceable> describes

I looked at this, and I think using a typedef makes it too complicated.
The idea is that "hook" should be a pointer to a function that has this
definition. Maybe we should change it to:

int hook(PGauthData type, PGconn *conn, void *data);
----

to match the line above:

void PQsetAuthDataHook(PQauthDataHook_type hook);

--
Bruce Momjian <bruce(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Do not let urgent matters crowd out time for investment in the future.