public inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Bruce Momjian <bruce@momjian.us>
To: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Improve PQauthDataHook_type docs
Date: Mon, 11 May 2026 19:07:57 -0400
Message-ID: <agJhTQ3fN-BR_i-2@momjian.us> (raw)
In-Reply-To: <CA+mi_8aEyKfLG3_+x7uU6HBYtOug3HYFRq1sz7JB7N89=EmKUA@mail.gmail.com>
References: <CA+mi_8aEyKfLG3_+x7uU6HBYtOug3HYFRq1sz7JB7N89=EmKUA@mail.gmail.com>
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.
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: bruce@momjian.us, daniele.varrazzo@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: Improve PQauthDataHook_type docs
In-Reply-To: <agJhTQ3fN-BR_i-2@momjian.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox