Hi,
On 2019-01-10 15:58:41 -0800, Andres Freund wrote:
> A number of postgres files have sections like heapam's
>
> * INTERFACE ROUTINES
> ...
> They're often out-of-date, and I personally never found them to be
> useful. A few people, including yours truly, have been removing a few
> here and there when overhauling a subsystem to avoid having to update
> and then adjust them.
>
> I think it might be a good idea to just do that for all at once. Having
> to consider separately committing a removal, updating them without
> fixing preexisting issues, or just leaving them outdated on a regular
> basis imo is a usless distraction.
As the reaction was positive, here's a first draft of a commit removing
them. A few comments:
- I left two INTERFACE ROUTINES blocks intact, because they actually add
somewhat useful information. Namely fd.c's, which actually seems
useful, and predicate.c's about which I'm less sure.
- I tried to move all comments about the routines in the INTERFACE
section to the functions if they didn't have a roughly equivalent
comment. Even if the comment wasn't that useful. Particularly just
about all the function comments in executor/node*.c files are useless,
but I thought that's something best to be cleaned up separately.
- After removing the INTERFACE ROUTINES blocks a number of executor
files had a separate comment block with just a NOTES section. I merged
these with the file header comment blocks, and indented them to
match. I think this is better, but I'm only like 60% convinced of
that.
Comments? I'll revisit this patch on Monday or so, make another pass
through it, and push it then.
Greetings,
Andres Freund
