Re: doc pg_constraint.convalidated column description need update

On Thu, May 1, 2025 at 10:19 PM jian he <jian.universality@gmail.com> wrote:
>
> hi.
>
> catalog.sgml:
>
>      <row>
>       <entry role="catalog_table_entry"><para role="column_definition">
>        <structfield>convalidated</structfield> <type>bool</type>
>       </para>
>       <para>
>        Has the constraint been validated?
>        Currently, can be false only for foreign keys and CHECK constraints
>       </para></entry>
>      </row>
>
> with NOT NULL NOT VALID,
> we need rephrase it to something like:
> "Currently, can be false only for foreign keys, CHECK and not-null constraints"
> I am also ok with just deleting it.
>

I actually think this mix of VALID / ENFORCED is a little convoluted
for end users, but I don't think the system catalog documentation is
the best place to work that out, and I see we've also not added this
type of extra information to other columns in the table that have
similar restrictions, so I think removing it is the right move.

As such, attached patch removes the above, and attempts some clean up
of the documentation in ALTER TABLE to better clarify the behavior
around valid/not valid, enforced/not enforced, and how it affects
different constraints, with some additional literal tag formatting
changes.

>
> BTW, I happen to notice a minor issue:
> some pg_catalog table column entry descriptions ending with a period,
> some didn't.
>

I don't know if it is intentional, but this seems to be determined by
a rough heuristic on if the description contains a complete
sentence(s) or not, but I would agree there are cases that don't
follow that, and some that could probably be argued either way. If it
were me I'd probably add punctuation to all of the entries, but others
may feel different.


Robert Treat
https://xzilla.net