From 9935a85fa4c69b45539e7800eed6c38779a75f0a Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 27 Dec 2001 21:36:57 +0000
Subject: [PATCH] Document obj_description and col_description functions;
expand description of COMMENT command.
---
doc/src/sgml/func.sgml | 66 +++++++++++++++++++++++++++++++++--
doc/src/sgml/ref/comment.sgml | 26 +++++++++++---
2 files changed, 85 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c9af36d5506..52f20f21584 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.88 2001/12/23 20:22:49 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.89 2001/12/27 21:36:57 tgl Exp $
PostgreSQL documentation
-->
@@ -2643,7 +2643,7 @@ PostgreSQL documentation
<row>
<entry><function>current_timestamp</function></entry>
<entry><type>timestamp</type></entry>
- <entry>date and time; see also <link
+ <entry>Date and time; see <link
linkend="functions-datetime-current">below</link>
</entry>
<entry></entry>
@@ -2722,7 +2722,7 @@ PostgreSQL documentation
<entry><function>now</function>()</entry>
<entry><type>timestamp</type></entry>
<entry>Current date and time (equivalent to
- <function>current_timestamp</function>); see also <link
+ <function>current_timestamp</function>); see <link
linkend="functions-datetime-current">below</link>
</entry>
<entry></entry>
@@ -4399,6 +4399,66 @@ SELECT NULLIF(value, '(none)') ...
<structfield>usesysid</> value.
</para>
+ <table>
+ <title>Comment Information Functions</>
+ <tgroup cols="3">
+ <thead>
+ <row><entry>Name</> <entry>Return Type</> <entry>Description</></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><function>obj_description</>(<parameter>objectOID</parameter>, <parameter>tablename</>)</entry>
+ <entry><type>text</></entry>
+ <entry>Get comment for a database object</>
+ </row>
+ <row>
+ <entry><function>obj_description</>(<parameter>objectOID</parameter>)</entry>
+ <entry><type>text</></entry>
+ <entry>Get comment for a database object (<emphasis>deprecated</>)</entry>
+ </row>
+ <row>
+ <entry><function>col_description</>(<parameter>tableOID</parameter>, <parameter>columnnumber</>)</entry>
+ <entry><type>text</></entry>
+ <entry>Get comment for a table column</>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <indexterm zone="functions-misc">
+ <primary>obj_description</primary>
+ </indexterm>
+
+ <indexterm zone="functions-misc">
+ <primary>col_description</primary>
+ </indexterm>
+
+ <para>
+ These functions extract comments previously stored with the
+ <command>COMMENT</> command. <literal>NULL</> is returned if
+ no comment can be found matching the specified parameters.
+ </para>
+
+ <para>
+ The two-parameter form of <function>obj_description()</> returns the
+ comment for a database object specified by its OID and the name of the
+ containing system catalog. For example,
+ <literal>obj_description(123456,'pg_class')</>
+ would retrieve the comment for a table with OID 123456.
+ The one-parameter form of <function>obj_description()</> requires only
+ the object OID. It is now deprecated since there is no guarantee that
+ OIDs are unique across different system catalogs; therefore, the wrong
+ comment could be returned.
+ </para>
+
+ <para>
+ <function>col_description()</> returns the comment for a table column,
+ which is specified by the OID of its table and its column number.
+ <function>obj_description()</> cannot be used for table columns since
+ columns do not have OIDs of their own.
+ </para>
+
</sect1>
diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index af4a3f65885..9a22b758954 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/comment.sgml,v 1.11 2001/12/08 03:24:34 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/comment.sgml,v 1.12 2001/12/27 21:36:57 tgl Exp $
PostgreSQL documentation
-->
@@ -98,12 +98,30 @@ COMMENT
Description
</title>
<para>
- <command>COMMENT</command> adds a comment to an object that can be
+ <command>COMMENT</command> stores a comment about a database object.
+ Comments can be
easily retrieved with <command>psql</command>'s
- <command>\dd</command>, <command>\d+</command>, or <command>\l+</command> commands.
- To remove a comment, write <literal>NULL</literal>.
+ <command>\dd</command>, <command>\d+</command>, or <command>\l+</command>
+ commands. Other user interfaces to retrieve comments can be built atop
+ the same built-in functions that <command>psql</command> uses, namely
+ <function>obj_description()</> and <function>col_description()</>.
+ </para>
+
+ <para>
+ To modify a comment, issue a new <command>COMMENT</> command for the
+ same object. Only one comment string is stored for each object.
+ To remove a comment, write <literal>NULL</literal> in place of the text
+ string.
Comments are automatically dropped when the object is dropped.
</para>
+
+ <para>
+ It should be noted that there is presently no security mechanism
+ for comments: any user connected to a database can see all the comments
+ for objects in that database (although only superusers can change
+ comments for objects that they don't own). Therefore, don't put
+ security-critical information in comments.
+ </para>
</refsect1>
<refsect1 id="R1-SQL-COMMENT-2">
--
GitLab