Thread: Outdated typedefs in documentation
Hi, I have noticed a slight mismatch between typedefs in docs and header files. On current master branch: - CustomScanState is missing custom_ps, pscan_len and slotOps fields in docs. - `methods` field of CustomPath, CustomScan and CustomScanState is missing `struct` in type. - BrinOpcInfo.oi_regular_nulls is missing. - pgNotify.next is missing. But the comment above it says apps should not use it, so I guess it can be left as is. Attached diff file shows other mismatches I could find. There are some comments that could be updated. Other differences are caused by indentation variations and false positives. The script I used for typedef extraction is also attached. Regards, Artem Fadeev. https://postgrespro.com
Attachment
> On 10 Jul 2025, at 02:45, Artem Fadeev <a.fadeev@postgrespro.ru> wrote: > Attached diff file shows other mismatches I could find. There are some > comments that could be updated. Other differences are caused by indentation variations and false positives. The attached diff is not useable for knowing what you propose to change, it's a mish-mash of incorrect proposal and unexplained comment removals against a file not present in our tree. Please make an actual patch against the docs you propose to change for us to have something to consider. -- Daniel Gustafsson
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.
"David G. Johnston" <david.g.johnston@gmail.com> writes:
> 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.
I'm dubious about that too. We should only put a real struct into
the documentation if it's part of a stable API for extensions to use.
Removing such a thing altogether would need to clear a very high bar.
But this script is also finding example structs that are not expected
to match anything in the code.
I'm more prepared to believe that there might be places where a
struct's documentation is out of sync with the code (e.g, missing
fields). And indeed Artem's script seems to have found some.
Those things should be fixed.
A lot of this, though, looks to be complaints because the comments
in the code don't exactly match the comments in the documentation.
I'm not clear whether "they should match exactly" is a useful goal.
The two cases are oriented towards different audiences.
regards, tom lane