agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Tom Lane <tgl@sss.pgh.pa.us>
To: David G. Johnston <david.g.johnston@gmail.com>
Cc: Artem Fadeev <a.fadeev@postgrespro.ru>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Outdated typedefs in documentation
Date: Thu, 10 Jul 2025 16:32:12 -0400
Message-ID: <1624549.1752179532@sss.pgh.pa.us> (raw)
In-Reply-To: <CAKFQuwbX=F_CpO9rJQ_sssAARKgx4iuNRkDNtoG7uupbeW9qkw@mail.gmail.com>
References: <4a742a5b-f081-4313-9241-b8392dfdb114@postgrespro.ru>
<CAKFQuwbX=F_CpO9rJQ_sssAARKgx4iuNRkDNtoG7uupbeW9qkw@mail.gmail.com>
"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
view thread (4+ messages)
Message-ID: <1624549.1752179532@sss.pgh.pa.us>
Permalink: ../1624549.1752179532@sss.pgh.pa.us/
Also on: postgresql.org/message-id/1624549.1752179532@sss.pgh.pa.us
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, david.g.johnston@gmail.com, a.fadeev@postgrespro.ru, pgsql-docs@lists.postgresql.org
Subject: Re: Outdated typedefs in documentation
In-Reply-To: <1624549.1752179532@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox