The COMMENT ref page says (and SECURITY LABEL similarly):
The name of the object to be commented. Names of tables,
aggregates, collations, ..., and views can be schema-qualified.
and it lists all such possible object types. I find this tedious to
read. (And there are omissions. For example materialized views are not
listed.) I wonder if it would be more practical to just write:
The name of the object to be commented. Names of objects that live
in schemas (tables, functions, etc.) can be schema-qualified.
There are also examples at the end that cover this if there is any doubt.
Patch attached. Thoughts?
From d5072256b1faabe516eb58990d6f89fa1a3bdd9f Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <pe...@eisentraut.org>
Date: Tue, 1 Jun 2021 08:50:40 +0200
Subject: [PATCH] doc: Simplify COMMENT and SECURITY LABEL documentation
Just say that objects that live in schemas can be schema-qualified.
Don't list all possible such objects. The existing lists weren't
complete anyway.
---
doc/src/sgml/ref/comment.sgml | 6 ++----
doc/src/sgml/ref/security_label.sgml | 5 ++---
2 files changed, 4 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index eda91b4e24..2cd47f65cc 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -129,10 +129,8 @@ <title>Parameters</title>
<term><replaceable class="parameter">trigger_name</replaceable></term>
<listitem>
<para>
- The name of the object to be commented. Names of tables,
- aggregates, collations, conversions, domains, foreign tables, functions,
- indexes, operators, operator classes, operator families, procedures,
routines, sequences,
- statistics, text search objects, types, and views can be
+ The name of the object to be commented. Names of objects that live in
+ schemas (tables, functions, etc.) can be
schema-qualified. When commenting on a column,
<replaceable class="parameter">relation_name</replaceable> must refer
to a table, view, composite type, or foreign table.
diff --git a/doc/src/sgml/ref/security_label.sgml
b/doc/src/sgml/ref/security_label.sgml
index 9b87bcd519..64606bf1fa 100644
--- a/doc/src/sgml/ref/security_label.sgml
+++ b/doc/src/sgml/ref/security_label.sgml
@@ -99,9 +99,8 @@ <title>Parameters</title>
<term><replaceable class="parameter">routine_name</replaceable></term>
<listitem>
<para>
- The name of the object to be labeled. Names of tables,
- aggregates, domains, foreign tables, functions, procedures, routines,
sequences, types, and
- views can be schema-qualified.
+ The name of the object to be labeled. Names of objects that live in
+ schemas (tables, functions, etc.) can be schema-qualified.
</para>
</listitem>
</varlistentry>
--
2.31.1
