Re: IWYU annotations

On 02.01.25 17:15, Tom Lane wrote:
>> 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.

In this updated patch set, I've just added a bit of info into
src/tools/pginclude/README. Updating the coding convention
documentation like you suggest also sounds like a good idea, but from my
perspective I would need to do further research to pin down what those
actually are, so I'm leaving that as a separate project.

(See for example the business in src/tools/pginclude/headerscheck about
guessing which the appropriate first header file should be for each
component. That kind of thing perhaps ought to be more formalized.)

> 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.

Yeah, that's a fair point. I have removed that part from my patch set.