"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
