Subject: Improve PQauthDataHook_type docs

From: Daniele Varrazzo <[email-masked]>
Date: Sun, 19 Apr 2026 16:54:02 +0100

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.

Cheers

-- Daniele
From 1925c2f47a268aa6a443b6f801c6ea7c1535ceed Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <[email-masked]>
Date: Sun, 19 Apr 2026 17:41:13 +0200
Subject: [PATCH] doc: improve PQauthDataHook_type definition

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
-- 
2.34.1

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 11 May 2026 19:07:57 -0400

>          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  <[email-masked]>        https://momjian.us
  EDB                                      https://enterprisedb.com

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