Re: Outdated typedefs in documentation

On Wed, Jul 9, 2025 at 5:46 PM Artem Fadeev <a(dot)fadeev(at)postgrespro(dot)ru> wrote:

> I have noticed a slight mismatch between typedefs in docs and header
> files.

Your code is producing obvious false-positives by finding documentation
examples and stating the obvious fact that such examples do not exist in
the code base (since they are examples).

The better algorithm is to first identify structs in the code that should
be documented. Then for each one search the docs and report whether it is
"present and matching", "present and not matching", or "not present".
Ideally ignoring comments since only the names/types and positions matter.
i.e., canonicalize the things being compared first. From that listing you
can then produce a patch to update the ones that aren't "present and
matching".

It seems mostly wasted effort to identify documented structs that are not
in the code - at least in an automated fashion. Documenting one and then
removing it outright - in way that someone might leave the documentation
for it behind - seems unlikely. But I'm guessing and maybe you will find
more than expected once you manually audit the results of such a scan and
produce a final clean report and, ideally, patch.

David J.