Date: Mon, 11 May 2026 19:07:57 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Improve PQauthDataHook_type docs
Message-ID: <agJhTQ3fN-BR_i-2@momjian.us>
References: 
 <CA+mi_8aEyKfLG3_+x7uU6HBYtOug3HYFRq1sz7JB7N89=EmKUA@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CA+mi_8aEyKfLG3_+x7uU6HBYtOug3HYFRq1sz7JB7N89=EmKUA@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/agJhTQ3fN-BR_i-2%40momjian.us>
Precedence: bulk

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.