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
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