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@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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