Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lnyMJ-0006ow-62 for pgsql-docs@arkaria.postgresql.org; Tue, 01 Jun 2021 06:58:39 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1lnyMI-0005aQ-3m for pgsql-docs@arkaria.postgresql.org; Tue, 01 Jun 2021 06:58:38 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lnyMH-0005aI-1d for pgsql-docs@lists.postgresql.org; Tue, 01 Jun 2021 06:58:37 +0000 Received: from forward4-smtp.messagingengine.com ([66.111.4.238]) by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lnyMB-0001zH-QR for pgsql-docs@postgresql.org; Tue, 01 Jun 2021 06:58:36 +0000 Received: from compute5.internal (compute5.nyi.internal [10.202.2.45]) by mailforward.nyi.internal (Postfix) with ESMTP id 5A4DC194090C for ; Tue, 1 Jun 2021 02:58:29 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute5.internal (MEProxy); Tue, 01 Jun 2021 02:58:29 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=content-type:date:from:message-id :mime-version:subject:to:x-me-proxy:x-me-proxy:x-me-sender :x-me-sender:x-sasl-enc; s=fm2; bh=6xBDv/DEhYMEuc6oFWZyBLLYuODc+ VelWMxNymtdsWw=; b=shSiz7aHu7hWSzMmsuwTgU4dUjeOb17Jv11F2rNeNkotN YfoqV3bPRYvSQDw/KxRExk+tGOJg3Db0+urLFGC7KzQQagGp3vmutF/gd7QNNA3L OgCfFAhYc/60DflnT18XyhMukdpMNcg3MYZ2NVwmKcwXsjuNGebyuBmgUPVrEAGm GWh1LHyNLHF+LV3V15gP3aWFlOSMnUyhrDBrUqRvk5Hc/0+7p/r8PGpm42GJjeiA IN3+Fcf0SzDR+q9nOCfZys/7h0bxLFhhnHBN+cFhoSZbSWqW04LuXJgD2ite3kfg AYSSophwngX33anWA42Rpgg4GLp+XGaBAiqfPl1Ew== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduledrvdelgedgudduhecutefuodetggdotefrod ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfgh necuuegrihhlohhuthemuceftddtnecunecujfgurhephffuvffkffgfgggtsehmtderre dtfeejnecuhfhrohhmpefrvghtvghrucfgihhsvghnthhrrghuthcuoehpvghtvghrrdgv ihhsvghnthhrrghuthesvghnthgvrhhprhhishgvuggsrdgtohhmqeenucggtffrrghtth gvrhhnpeejteehveeuueeuudevteekgeefieefveettdeukeevteekffffieejheffgfej leenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehpvg htvghrrdgvihhsvghnthhrrghuthesvghnthgvrhhprhhishgvuggsrdgtohhm X-ME-Proxy: Received: by mail.messagingengine.com (Postfix) with ESMTPA for ; Tue, 1 Jun 2021 02:58:27 -0400 (EDT) From: Peter Eisentraut Subject: Simplify COMMENT and SECURITY LABEL documentation To: pgsql-docs Message-ID: Date: Tue, 1 Jun 2021 08:58:26 +0200 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:78.0) Gecko/20100101 Thunderbird/78.10.2 MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="------------045935D3B5F87228E772C5A6" Content-Language: en-US List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk This is a multi-part message in MIME format. --------------045935D3B5F87228E772C5A6 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit 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? --------------045935D3B5F87228E772C5A6 Content-Type: text/plain; charset=UTF-8; x-mac-type="0"; x-mac-creator="0"; name="0001-doc-Simplify-COMMENT-and-SECURITY-LABEL-documentatio.patch" Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename*0="0001-doc-Simplify-COMMENT-and-SECURITY-LABEL-documentatio.pa"; filename*1="tch" RnJvbSBkNTA3MjI1NmIxZmFhYmU1MTZlYjU4OTkwZDZmODlmYTFhM2JkZDlmIE1vbiBTZXAg MTcgMDA6MDA6MDAgMjAwMQpGcm9tOiBQZXRlciBFaXNlbnRyYXV0IDxwZXRlckBlaXNlbnRy YXV0Lm9yZz4KRGF0ZTogVHVlLCAxIEp1biAyMDIxIDA4OjUwOjQwICswMjAwClN1YmplY3Q6 IFtQQVRDSF0gZG9jOiBTaW1wbGlmeSBDT01NRU5UIGFuZCBTRUNVUklUWSBMQUJFTCBkb2N1 bWVudGF0aW9uCgpKdXN0IHNheSB0aGF0IG9iamVjdHMgdGhhdCBsaXZlIGluIHNjaGVtYXMg Y2FuIGJlIHNjaGVtYS1xdWFsaWZpZWQuCkRvbid0IGxpc3QgYWxsIHBvc3NpYmxlIHN1Y2gg b2JqZWN0cy4gIFRoZSBleGlzdGluZyBsaXN0cyB3ZXJlbid0CmNvbXBsZXRlIGFueXdheS4K LS0tCiBkb2Mvc3JjL3NnbWwvcmVmL2NvbW1lbnQuc2dtbCAgICAgICAgfCA2ICsrLS0tLQog ZG9jL3NyYy9zZ21sL3JlZi9zZWN1cml0eV9sYWJlbC5zZ21sIHwgNSArKy0tLQogMiBmaWxl cyBjaGFuZ2VkLCA0IGluc2VydGlvbnMoKyksIDcgZGVsZXRpb25zKC0pCgpkaWZmIC0tZ2l0 IGEvZG9jL3NyYy9zZ21sL3JlZi9jb21tZW50LnNnbWwgYi9kb2Mvc3JjL3NnbWwvcmVmL2Nv bW1lbnQuc2dtbAppbmRleCBlZGE5MWI0ZTI0Li4yY2Q0N2Y2NWNjIDEwMDY0NAotLS0gYS9k b2Mvc3JjL3NnbWwvcmVmL2NvbW1lbnQuc2dtbAorKysgYi9kb2Mvc3JjL3NnbWwvcmVmL2Nv bW1lbnQuc2dtbApAQCAtMTI5LDEwICsxMjksOCBAQCA8dGl0bGU+UGFyYW1ldGVyczwvdGl0 bGU+CiAgICAgPHRlcm0+PHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPnRyaWdnZXJf bmFtZTwvcmVwbGFjZWFibGU+PC90ZXJtPgogICAgIDxsaXN0aXRlbT4KICAgICAgPHBhcmE+ Ci0gICAgICBUaGUgbmFtZSBvZiB0aGUgb2JqZWN0IHRvIGJlIGNvbW1lbnRlZC4gIE5hbWVz IG9mIHRhYmxlcywKLSAgICAgIGFnZ3JlZ2F0ZXMsIGNvbGxhdGlvbnMsIGNvbnZlcnNpb25z LCBkb21haW5zLCBmb3JlaWduIHRhYmxlcywgZnVuY3Rpb25zLAotICAgICAgaW5kZXhlcywg b3BlcmF0b3JzLCBvcGVyYXRvciBjbGFzc2VzLCBvcGVyYXRvciBmYW1pbGllcywgcHJvY2Vk dXJlcywgcm91dGluZXMsIHNlcXVlbmNlcywKLSAgICAgIHN0YXRpc3RpY3MsIHRleHQgc2Vh cmNoIG9iamVjdHMsIHR5cGVzLCBhbmQgdmlld3MgY2FuIGJlCisgICAgICBUaGUgbmFtZSBv ZiB0aGUgb2JqZWN0IHRvIGJlIGNvbW1lbnRlZC4gIE5hbWVzIG9mIG9iamVjdHMgdGhhdCBs aXZlIGluCisgICAgICBzY2hlbWFzICh0YWJsZXMsIGZ1bmN0aW9ucywgZXRjLikgY2FuIGJl CiAgICAgICBzY2hlbWEtcXVhbGlmaWVkLiBXaGVuIGNvbW1lbnRpbmcgb24gYSBjb2x1bW4s CiAgICAgICA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+cmVsYXRpb25fbmFtZTwv cmVwbGFjZWFibGU+IG11c3QgcmVmZXIKICAgICAgIHRvIGEgdGFibGUsIHZpZXcsIGNvbXBv c2l0ZSB0eXBlLCBvciBmb3JlaWduIHRhYmxlLgpkaWZmIC0tZ2l0IGEvZG9jL3NyYy9zZ21s L3JlZi9zZWN1cml0eV9sYWJlbC5zZ21sIGIvZG9jL3NyYy9zZ21sL3JlZi9zZWN1cml0eV9s YWJlbC5zZ21sCmluZGV4IDliODdiY2Q1MTkuLjY0NjA2YmYxZmEgMTAwNjQ0Ci0tLSBhL2Rv Yy9zcmMvc2dtbC9yZWYvc2VjdXJpdHlfbGFiZWwuc2dtbAorKysgYi9kb2Mvc3JjL3NnbWwv cmVmL3NlY3VyaXR5X2xhYmVsLnNnbWwKQEAgLTk5LDkgKzk5LDggQEAgPHRpdGxlPlBhcmFt ZXRlcnM8L3RpdGxlPgogICAgIDx0ZXJtPjxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVy Ij5yb3V0aW5lX25hbWU8L3JlcGxhY2VhYmxlPjwvdGVybT4KICAgICA8bGlzdGl0ZW0+CiAg ICAgIDxwYXJhPgotICAgICAgVGhlIG5hbWUgb2YgdGhlIG9iamVjdCB0byBiZSBsYWJlbGVk LiAgTmFtZXMgb2YgdGFibGVzLAotICAgICAgYWdncmVnYXRlcywgZG9tYWlucywgZm9yZWln biB0YWJsZXMsIGZ1bmN0aW9ucywgcHJvY2VkdXJlcywgcm91dGluZXMsIHNlcXVlbmNlcywg dHlwZXMsIGFuZAotICAgICAgdmlld3MgY2FuIGJlIHNjaGVtYS1xdWFsaWZpZWQuCisgICAg ICBUaGUgbmFtZSBvZiB0aGUgb2JqZWN0IHRvIGJlIGxhYmVsZWQuICBOYW1lcyBvZiBvYmpl Y3RzIHRoYXQgbGl2ZSBpbgorICAgICAgc2NoZW1hcyAodGFibGVzLCBmdW5jdGlvbnMsIGV0 Yy4pIGNhbiBiZSBzY2hlbWEtcXVhbGlmaWVkLgogICAgICA8L3BhcmE+CiAgICAgPC9saXN0 aXRlbT4KICAgIDwvdmFybGlzdGVudHJ5PgotLSAKMi4zMS4xCgo= --------------045935D3B5F87228E772C5A6--