Re: IWYU annotations

Peter Eisentraut <peter(at)eisentraut(dot)org> writes:
> On 09.12.24 17:37, Tom Lane wrote:
>> In particular, this patchset introduces what seem like very
>> error-prone setups, such as in rmgrdesc.c where there's now one
>> group of #include's with "pragma: begin_keep/pragma: end_keep"
>> around it and another group without. Most of us are likely
>> to just blindly stick a new #include into alphabetical order
>> somewhere in there and not notice that there's now an additional
>> concern. The fact that that you've added precisely zero
>> documentation about what these pragmas are doesn't help.

> It's a fair point that some documentation could be provided. I suppose
> we don't want to verbosely explain each pragma individually. Should
> there be some central explanation, maybe in src/tools/pginclude/README?

That might do, but perhaps instead in the "PostgreSQL Coding
Conventions" chapter of the SGML docs? Actually, I think we could do
with a centralized explanation of our inclusion conventions --- I'm
not sure that the whole business of "postgres.h or a sibling must be
first" is explained in any easy-to-find place. This topic would
likely fit well with such an explanation.

But really, the point I was trying to make above is that I don't
want this to break our very long-standing convention that headers
should be #include'd alphabetically and there is never a need to
impose some other order (at least not without lots of commentary
about it at the scene of the crime). The way you've done it here
is just asking for trouble, IMO. If that means redundant pragma
commands, so be it.

regards, tom lane