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
