Re: IWYU annotations

On 10.01.25 09:10, Peter Eisentraut wrote:
> 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.

I have committed this.  Thanks for the feedback.