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(at)eisentraut(dot)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.