public inbox for pgsql-docs@postgresql.orghelp / color / mirror / Atom feed
Improve PQauthDataHook_type docs 2+ messages / 2 participants [nested] [flat]
* Improve PQauthDataHook_type docs @ 2026-04-19 15:54 Daniele Varrazzo <daniele.varrazzo@gmail.com> 2026-05-11 23:07 ` Re: Improve PQauthDataHook_type docs Bruce Momjian <bruce@momjian.us> 0 siblings, 1 reply; 2+ messages in thread From: Daniele Varrazzo @ 2026-04-19 15:54 UTC (permalink / raw) To: pgsql-docs@lists.postgresql.org 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 Attachments: [text/x-patch] 0001-doc-improve-PQauthDataHook_type-definition.patch (1.1K, 2-0001-doc-improve-PQauthDataHook_type-definition.patch) download | inline diff: From 1925c2f47a268aa6a443b6f801c6ea7c1535ceed Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo <daniele.varrazzo@gmail.com> 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 ^ permalink raw reply [nested|flat] 2+ messages in thread
* Re: Improve PQauthDataHook_type docs 2026-04-19 15:54 Improve PQauthDataHook_type docs Daniele Varrazzo <daniele.varrazzo@gmail.com> @ 2026-05-11 23:07 ` Bruce Momjian <bruce@momjian.us> 0 siblings, 0 replies; 2+ messages in thread From: Bruce Momjian @ 2026-05-11 23:07 UTC (permalink / raw) To: Daniele Varrazzo <daniele.varrazzo@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org 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. ^ permalink raw reply [nested|flat] 2+ messages in thread
end of thread, other threads:[~2026-05-11 23:07 UTC | newest] Thread overview: 2+ messages (download: mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2026-04-19 15:54 Improve PQauthDataHook_type docs Daniele Varrazzo <daniele.varrazzo@gmail.com> 2026-05-11 23:07 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox