On Wed, 2026-10-07 at 11:23 +0000, PG Doc comments form wrote:
> Page: https://www.postgresql.org/docs/18/sql-altertable.html
>
> after spending some time searching for how to do comments, maybe some
> documentation could be made clearer:
>
> links from 'create table', 'alter table' to
> https://www.postgresql.org/docs/current/sql-comment.html (maybe in the 'see
> also' section).
>
> and in 'comment' part, mention that comments on columns can be seen with \d+
> and comments on tables with \dt+ (\dv+ on views)
> so from 'Comments can be viewed using psql's \d family of commands.' to
> something like 'Comments can be viewed using psql's \d family of commands.
> To see comments on columns, use \d+ table_name command, for comment on the
> table itself, use \dt+ table_name command'.
Cross references are a good thing. But we should be careful not to repeat
everything everywhere. I pretended to be clueless and both looked in
the index (where the COMMENT command is referenced) and used the search
for "table comment", which also took me right to the COMMENT command.
So that is pretty straightforward to find.
As you mention, that page points you to psql's \d commands.
Searching for "comment" on that page, I quickly found the \dd metacommand
(TIL!), which shown comments on some types of objects. Also, it points
you to the \d commands for the respective object types to see comments on
those. There I quickly found that \d<whatever>+ will show the description.
So I think that it is easy enough to find the information.
On the other hand, there is always room for improvement. You suggest to
specifically mention \d+ and \dt+ in the COMMENT documentation. I can
understand that wish, since it were comments on those objects that you
were looking for. But it feels undesirable to me to only mention some
object types and not the others. How would you feel about something like
Comments can be viewed using psql's \d family of commands, in particular
\dd and the + suffix for the \d commands.
Yours,
Laurenz Albe
