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.