Re: Outdated typedefs in documentation - Mailing list pgsql-docs

From David G. Johnston
Subject Re: Outdated typedefs in documentation
Date
Msg-id CAKFQuwbX=F_CpO9rJQ_sssAARKgx4iuNRkDNtoG7uupbeW9qkw@mail.gmail.com
Whole thread Raw
In response to Outdated typedefs in documentation  (Artem Fadeev <a.fadeev@postgrespro.ru>)
Responses Re: Outdated typedefs in documentation
List pgsql-docs
On Wed, Jul 9, 2025 at 5:46 PM Artem Fadeev <a.fadeev@postgrespro.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.

pgsql-docs by date:

Previous
From: Daniel Gustafsson
Date:
Subject: Re: Outdated typedefs in documentation
Next
From: Tom Lane
Date:
Subject: Re: Outdated typedefs in documentation