agora inbox for [email protected]
help / color / mirror / Atom feedImprove PQauthDataHook_type docs
5+ messages / 5 participants
[nested] [flat]
* Improve PQauthDataHook_type docs
@ 2026-04-19 15:54 Daniele Varrazzo <[email protected]>
2026-05-11 23:07 ` Re: Improve PQauthDataHook_type docs Bruce Momjian <[email protected]>
0 siblings, 1 reply; 5+ messages in thread
From: Daniele Varrazzo @ 2026-04-19 15:54 UTC (permalink / raw)
To: [email protected]
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, ../../CA+mi_8aEyKfLG3_+x7uU6HBYtOug3HYFRq1sz7JB7N89=EmKUA@mail.gmail.com/2-0001-doc-improve-PQauthDataHook_type-definition.patch)
download | inline diff:
From 1925c2f47a268aa6a443b6f801c6ea7c1535ceed Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <[email protected]>
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] 5+ messages in thread
* Re: Improve PQauthDataHook_type docs
2026-04-19 15:54 Improve PQauthDataHook_type docs Daniele Varrazzo <[email protected]>
@ 2026-05-11 23:07 ` Bruce Momjian <[email protected]>
0 siblings, 0 replies; 5+ messages in thread
From: Bruce Momjian @ 2026-05-11 23:07 UTC (permalink / raw)
To: Daniele Varrazzo <[email protected]>; +Cc: [email protected]
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 <[email protected]> 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] 5+ messages in thread
* remark regarding 4.2.13. Row Constructors
@ 2026-06-08 07:42 PG Doc comments form <[email protected]>
2026-06-09 08:06 ` Re: remark regarding 4.2.13. Row Constructors Daniel Gustafsson <[email protected]>
0 siblings, 1 reply; 5+ messages in thread
From: PG Doc comments form @ 2026-06-08 07:42 UTC (permalink / raw)
To: [email protected]; +Cc: [email protected]
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/18/sql-expressions.html
Description:
Hi,
in
https://www.postgresql.org/docs/current/sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS
there is:
"The key word ROW is optional when there is more than one expression in the
list."
I think it should be:
"The key word ROW is optional when there are more than zero expressions in
the list."
Test Case:
[postgres@lin5 ~]$ psql mydb
psql (19beta1)
Type "help" for help.
mydb=# select (1);
?column?
----------
1
(1 row)
mydb=# select (1,2);
row
-------
(1,2)
(1 row)
mydb=# select ();
ERROR: syntax error at or near ")"
LINE 1: select ();
^
mydb=# select row();
row
-----
()
(1 row)
mydb=#
Regards
Jochen
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: remark regarding 4.2.13. Row Constructors
2026-06-08 07:42 remark regarding 4.2.13. Row Constructors PG Doc comments form <[email protected]>
@ 2026-06-09 08:06 ` Daniel Gustafsson <[email protected]>
2026-06-09 16:46 ` Re: remark regarding 4.2.13. Row Constructors Tom Lane <[email protected]>
0 siblings, 1 reply; 5+ messages in thread
From: Daniel Gustafsson @ 2026-06-09 08:06 UTC (permalink / raw)
To: [email protected]; PostgreSQL-documentation <[email protected]>
> On 8 Jun 2026, at 09:42, PG Doc comments form <[email protected]> wrote:
> in
> https://www.postgresql.org/docs/current/sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS
> there is:
> "The key word ROW is optional when there is more than one expression in the
> list."
> I think it should be:
> "The key word ROW is optional when there are more than zero expressions in
> the list."
"more than zero" sounds a bit odd, my suggestion would be "The key word ROW is
optional when there is one, or more, expressions in the list."
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: remark regarding 4.2.13. Row Constructors
2026-06-08 07:42 remark regarding 4.2.13. Row Constructors PG Doc comments form <[email protected]>
2026-06-09 08:06 ` Re: remark regarding 4.2.13. Row Constructors Daniel Gustafsson <[email protected]>
@ 2026-06-09 16:46 ` Tom Lane <[email protected]>
0 siblings, 0 replies; 5+ messages in thread
From: Tom Lane @ 2026-06-09 16:46 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; +Cc: [email protected]; PostgreSQL-documentation <[email protected]>
Daniel Gustafsson <[email protected]> writes:
>> On 8 Jun 2026, at 09:42, PG Doc comments form <[email protected]> wrote:
>> in
>> https://www.postgresql.org/docs/current/sql-expressions.html#SQL-SYNTAX-ROW-CONSTRUCTORS
>> there is:
>> "The key word ROW is optional when there is more than one expression in the
>> list."
>> I think it should be:
>> "The key word ROW is optional when there are more than zero expressions in
>> the list."
> "more than zero" sounds a bit odd, my suggestion would be "The key word ROW is
> optional when there is one, or more, expressions in the list."
More to the point, the statement is correct as written and either of
these changes would make it wrong. For example, both of these things
produce a two-column composite value:
postgres=# select row(1,2), (1,2);
row | row
-------+-------
(1,2) | (1,2)
(1 row)
postgres=# select pg_typeof(row(1,2)), pg_typeof((1,2));
pg_typeof | pg_typeof
-----------+-----------
record | record
(1 row)
But adding more parentheses around a scalar value does not make
it a composite value:
postgres=# select row(1), (1), ((((1))));
row | ?column? | ?column?
-----+----------+----------
(1) | 1 | 1
(1 row)
postgres=# select pg_typeof(row(1)), pg_typeof((1)), pg_typeof(((((1)))));
pg_typeof | pg_typeof | pg_typeof
-----------+-----------+-----------
record | integer | integer
(1 row)
Maybe there is something we can do to make this clearer, but
the above isn't it.
regards, tom lane
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2026-06-09 16:46 UTC | newest]
Thread overview: 5+ messages (download: mbox 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 <[email protected]>
2026-05-11 23:07 ` Bruce Momjian <[email protected]>
2026-06-08 07:42 remark regarding 4.2.13. Row Constructors PG Doc comments form <[email protected]>
2026-06-09 08:06 ` Re: remark regarding 4.2.13. Row Constructors Daniel Gustafsson <[email protected]>
2026-06-09 16:46 ` Re: remark regarding 4.2.13. Row Constructors Tom Lane <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox