Clean up code comments for pg_wchar_tbl

Started by Peter Eisentraut26 days ago5 messageshackers
Jump to latest
#1Peter Eisentraut
peter@eisentraut.org

The documentation for the functions in the fields of pg_wchar_tbl was
spread out all over the place and was missing a lot of detail. I
propose the attached patch that moves the important material into the
definition of the struct and also expands the details a bit, so that all
the important info is in one easy to find place. Some of those details
I gathered and inferred from various places, and some of those used to
be more like "it works this way" where I'm now somewhat elevating it to
"it is supposed to work this way", so maybe that's worth double-checking.

I'm also removing some unnecessary typedefs for those functions, except
where they were used elsewhere to hold local variables. This
indirection made the code documentation harder to follow. And some of
those typedefs had nonsensical names, like *_converter for functions
that didn't do any converting.

(I was looking for example at struct TableAmRoutine in access/tableam.h
for inspiration for a well-commented callback table definition.)

Attachments:

t254411_1
0001-Clean-up-code-comments-for-pg_wchar_tbl.patchtext/plain; charset=UTF-8; name=0001-Clean-up-code-comments-for-pg_wchar_tbl.patchDownload+113-91
#2Greg Burd
greg@burd.me
In reply to: Peter Eisentraut (#1)
Re: Clean up code comments for pg_wchar_tbl

On Tuesday, October 27th, 2026 at 10:33 AM, Peter Eisentraut <peter@eisentraut.org> wrote:

The documentation for the functions in the fields of pg_wchar_tbl was
spread out all over the place and was missing a lot of detail. I
propose the attached patch that moves the important material into the
definition of the struct and also expands the details a bit, so that all
the important info is in one easy to find place. Some of those details
I gathered and inferred from various places, and some of those used to
be more like "it works this way" where I'm now somewhat elevating it to
"it is supposed to work this way", so maybe that's worth double-checking.

I'm also removing some unnecessary typedefs for those functions, except
where they were used elsewhere to hold local variables. This
indirection made the code documentation harder to follow. And some of
those typedefs had nonsensical names, like *_converter for functions
that didn't do any converting.

(I was looking for example at struct TableAmRoutine in access/tableam.h
for inspiration for a well-commented callback table definition.)

Hello Peter,

I read over the patch, two things. First, thanks for doing these kinds of
clean-up patches. Second, looks good. I saw other things I'd change if I
were doing a cleanup beyond comments, but for a focused fix I'm +1.

nit:

s/These functions generally assume that their input is validly formed/These functions generally assume that their input is well formed and valid/

best.

-greg

#3Andreas Karlsson
andreas.karlsson@percona.com
In reply to: Greg Burd (#2)
Re: Clean up code comments for pg_wchar_tbl

On 10/27/26 6:18 PM, Greg Burd wrote:

nit:

s/These functions generally assume that their input is validly formed/These functions generally assume that their input is well formed and valid/

I have not read the rest of the patch yet but as a non-native speaker
the original wording is more clear and your suggested change makes it
seem like "well-formed" and "valid" might be two separate properties.

I think any of the original, "validly formed", or "valid" or
"well-formed" would work.

--
Andreas Karlsson
Percona

#4Joel Jacobson
joel@compiler.org
In reply to: Greg Burd (#2)
Re: Clean up code comments for pg_wchar_tbl

On Tue, Oct 27, 2026, at 18:18, Greg Burd wrote:

nit:

s/These functions generally assume that their input is validly
formed/These functions generally assume that their input is well formed
and valid/

What additional requirement does "and valid" express beyond being well formed in the relevant encoding?

/Joel

Show quoted text

best.

-greg

#5Peter Eisentraut
peter@eisentraut.org
In reply to: Greg Burd (#2)
Re: Clean up code comments for pg_wchar_tbl

On 27.10.26 18:18, Greg Burd wrote:

On Tuesday, October 27th, 2026 at 10:33 AM, Peter Eisentraut <peter@eisentraut.org> wrote:

The documentation for the functions in the fields of pg_wchar_tbl was
spread out all over the place and was missing a lot of detail. I
propose the attached patch that moves the important material into the
definition of the struct and also expands the details a bit, so that all
the important info is in one easy to find place. Some of those details
I gathered and inferred from various places, and some of those used to
be more like "it works this way" where I'm now somewhat elevating it to
"it is supposed to work this way", so maybe that's worth double-checking.

I'm also removing some unnecessary typedefs for those functions, except
where they were used elsewhere to hold local variables. This
indirection made the code documentation harder to follow. And some of
those typedefs had nonsensical names, like *_converter for functions
that didn't do any converting.

(I was looking for example at struct TableAmRoutine in access/tableam.h
for inspiration for a well-commented callback table definition.)

Hello Peter,

I read over the patch, two things. First, thanks for doing these kinds of
clean-up patches. Second, looks good. I saw other things I'd change if I
were doing a cleanup beyond comments, but for a focused fix I'm +1.

Committed, thanks.

s/These functions generally assume that their input is validly formed/These functions generally assume that their input is well formed and valid/

Hmm, the Unicode standard uses well-formed and valid for different
things. I'm not sure which one applies here. It might be worth sorting
this out and cleaning this up across all these files. For now I have
left the original wording.