Skip to content

Commit b6d6cff

Browse files
bmomjianbmomjian
committed
Add documentation for comment.
1 parent 577e21b commit b6d6cff

File tree

2 files changed

+210
-41
lines changed

2 files changed

+210
-41
lines changed

‎doc/src/sgml/ref/comment.sgml

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
<!--
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/comment.sgml,v 1.1 1999/10/26 03:48:58 momjian Exp $
3+
Postgres documentation
4+
-->
5+
6+
<refentry id="SQL-COMMENT">
7+
<refmeta>
8+
<refentrytitle id="SQL-COMMENT-TITLE">
9+
COMMENT
10+
</refentrytitle>
11+
<refmiscinfo>SQL - Language Statements</refmiscinfo>
12+
</refmeta>
13+
<refnamediv>
14+
<refname>
15+
COMMENT
16+
</refname>
17+
<refpurpose>
18+
Add comment to an object
19+
</refpurpose>
20+
</refnamediv>
21+
<refsynopsisdiv>
22+
<refsynopsisdivinfo>
23+
<date>1999-07-20</date>
24+
</refsynopsisdivinfo>
25+
<synopsis>
26+
COMMENT ON
27+
[
28+
[ DATABASE | INDEX | RULE | SEQUENCE | TABLE | TYPE | VIEW ]
29+
<replaceable class="PARAMETER">object_name</replaceable> |
30+
COLUMN <replaceable class="PARAMETER">table_name</replaceable>.<replaceable class="PARAMETER">column_name</replaceable>|
31+
AGGREGATE <replaceable class="PARAMETER">agg_name</replaceable> <replaceable class="PARAMETER">agg_type</replaceable>|
32+
FUNCTION <replaceable class="PARAMETER">func_name</replaceable> (<replaceable class="PARAMETER">arg1</replaceable>, <replaceable class="PARAMETER">arg2</replaceable>, ...)|
33+
OPERATOR <replaceable class="PARAMETER">op</replaceable> (<replaceable class="PARAMETER">leftoperand_type</replaceable> <replaceable class="PARAMETER">rightoperand_type</replaceable>) |
34+
TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable>
35+
] IS <replaceable class="PARAMETER">'text'</replaceable>
36+
</synopsis>
37+
38+
<refsect2 id="R2-SQL-COMMENT-1">
39+
<refsect2info>
40+
<date>1999-10-25</date>
41+
</refsect2info>
42+
<title>
43+
Inputs
44+
</title>
45+
<para>
46+
47+
<variablelist>
48+
<varlistentry>
49+
<term><replaceable class="PARAMETER">object_name, table_name,
50+
column_name, agg_name, func_name, op, trigger_name</replaceable></term>
51+
<listitem>
52+
<para>
53+
The name of the object to be be commented.
54+
</para>
55+
</listitem>
56+
</varlistentry>
57+
<varlistentry>
58+
<term><replaceable class="PARAMETER">text</replaceable></term>
59+
<listitem>
60+
<para>
61+
The comment to add.
62+
</para>
63+
</listitem>
64+
</varlistentry>
65+
</variablelist>
66+
</para>
67+
</refsect2>
68+
69+
<refsect2 id="R2-SQL-COMMENT-2">
70+
<refsect2info>
71+
<date>1998-09-08</date>
72+
</refsect2info>
73+
<title>
74+
Outputs
75+
</title>
76+
<para>
77+
78+
<variablelist>
79+
<varlistentry>
80+
<term><computeroutput>
81+
COMMENT
82+
</computeroutput></term>
83+
<listitem>
84+
<para>
85+
Message returned if the table is successfully commented.
86+
</para>
87+
</listitem>
88+
</varlistentry>
89+
</variablelist>
90+
</para>
91+
</refsect2>
92+
</refsynopsisdiv>
93+
94+
<refsect1 id="R1-SQL-COMMENT-1">
95+
<refsect1info>
96+
<date>1998-10-25</date>
97+
</refsect1info>
98+
<title>
99+
Description
100+
</title>
101+
<para>
102+
<command>COMMENT</command> adds a comment to an object that can be
103+
easily retrieved with <application>psql's</application>
104+
<emphasize>\dd</emphasize> command.
105+
To remove a comment, use <literal>''</literal>.
106+
</para>
107+
</refsect1>
108+
109+
<refsect1 id="R1-SQL-COMMENT-2">
110+
<title>
111+
Usage
112+
</title>
113+
<para>
114+
comment the table <literal>mytable</literal>:
115+
116+
<programlisting>
117+
COMMENT ON mytable IS 'This is my table.';
118+
</programlisting>
119+
</para>
120+
</refsect1>
121+
122+
<refsect1 id="R1-SQL-COMMENT-3">
123+
<title>
124+
Compatibility
125+
</title>
126+
127+
<refsect2 id="R2-SQL-COMMENT-4">
128+
<refsect2info>
129+
<date>1998-09-08</date>
130+
</refsect2info>
131+
<title>
132+
SQL92
133+
</title>
134+
<para>
135+
There is no <command>COMMENT</command> in <acronym>SQL92</acronym>.
136+
</para>
137+
</refsect2>
138+
</refsect1>
139+
</refentry>
140+
141+
<!-- Keep this comment at the end of the file
142+
Local variables:
143+
mode: sgml
144+
sgml-omittag:t
145+
sgml-shorttag:t
146+
sgml-minimize-attributes:nil
147+
sgml-always-quote-attributes:t
148+
sgml-indent-step:1
149+
sgml-indent-data:t
150+
sgml-parent-document:nil
151+
sgml-default-dtd-file:"../reference.ced"
152+
sgml-exposed-tags:nil
153+
sgml-local-catalogs:"/usr/lib/sgml/catalog"
154+
sgml-local-ecat-files:nil
155+
End:
156+
-->

‎src/bin/psql/psqlHelp.h

Lines changed: 54 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
*
66
* Copyright (c) 1994, Regents of the University of California
77
*
8-
* $Id: psqlHelp.h,v 1.77 1999/10/02 21:33:29 tgl Exp $
8+
* $Id: psqlHelp.h,v 1.78 1999/10/26 03:48:58 momjian Exp $
99
*
1010
*-------------------------------------------------------------------------
1111
*/
@@ -25,9 +25,9 @@ static struct _helpStruct QL_HELP[] = {
2525
{"alter table",
2626
"add/rename columns, rename tables",
2727
"\
28-
\tALTER TABLE tablename [*] ADD COLUMN colname type\n\
29-
\tALTER TABLE tablename [*] RENAME [COLUMN] colname1 TO colname2\n\
30-
\tALTER TABLE tablename1 RENAME TO tablename2"},
28+
\tALTER TABLE table_name [*] ADD COLUMN column_name type\n\
29+
\tALTER TABLE table_name [*] RENAME [COLUMN] column_name1 TO column_name2\n\
30+
\tALTER TABLE table_name1 RENAME TO table_name2"},
3131
{"alter user",
3232
"alter system information for a user",
3333
"\
@@ -41,22 +41,34 @@ static struct _helpStruct QL_HELP[] = {
4141
"begin a new transaction",
4242
"\
4343
\tBEGIN [WORK|TRANSACTION];"},
44-
{"cluster",
45-
"create a clustered index (from an existing index)",
46-
"\
47-
\tCLUSTER index_name ON relation_name"},
4844
{"close",
4945
"close an existing cursor (cursor)",
5046
"\
5147
\tCLOSE cursorname;"},
48+
{"cluster",
49+
"create a clustered index (from an existing index)",
50+
"\
51+
\tCLUSTER index_name ON relation_name"},
52+
{"comment",
53+
"add comment on object",
54+
"\
55+
\tCOMMENT ON\n\
56+
[\n\
57+
[ DATABASE | INDEX | RULE | SEQUENCE | TABLE | TYPE | VIEW ] <object_name> |\n\
58+
COLUMN <table_name>.<column_name>|\n\
59+
AGGREGATE <agg_name> <agg_type>|\n\
60+
FUNCTION <func_name> (arg1, arg2, ...)|\n\
61+
OPERATOR <op> (leftoperand_type rightoperand_type) |\n\
62+
TRIGGER <trigger_name> ON <table_name>\n\
63+
] IS 'text'},
5264
{"commit work",
5365
"commit a transaction",
5466
"\
5567
\tCOMMIT [WORK|TRANSACTION]"},
5668
{"copy",
5769
"copy data to and from a table",
5870
"\
59-
\tCOPY [BINARY] tablename [WITH OIDS]\n\
71+
\tCOPY [BINARY] table_name [WITH OIDS]\n\
6072
\tTO|FROM filename|STDIN|STDOUT [USING DELIMITERS 'delim'];"},
6173
{"create",
6274
"Please be more specific:",
@@ -88,21 +100,22 @@ static struct _helpStruct QL_HELP[] = {
88100
"create a user-defined function",
89101
"\
90102
\tCREATE FUNCTION function_name ([type1, ...typeN]) RETURNS return_type\n\
91-
\t[WITH ( attributes )]\n\
103+
\t[WITH ( column_names )]\n\
92104
\tAS 'sql_queries'|'builtin_function_name'|'procedural_commands'\n\
93105
\tLANGUAGE 'sql'|'internal'|'procedural_language_name';\n\
94106
\n\
95107
OR\n\
96108
\n\
97109
\tCREATE FUNCTION function_name ([type1, ...typeN]) RETURNS return_type\n\
98-
\t[WITH ( attributes )]\n\
110+
\t[WITH ( column_names )]\n\
99111
\tAS 'object_filename' [, 'link_symbol']\n\
100112
\tLANGUAGE 'C';"},
101113
{"create index",
102114
"construct an index",
103115
"\
104-
\tCREATE [UNIQUE] INDEX indexname ON tablename [USING access_method]\n\
105-
( colname1 [type_class1], ...colnameN | funcname(colname1, ...) [type_class] );"},
116+
\tCREATE [UNIQUE] INDEX indexname ON table_name [USING access_method]\n\
117+
( column_name1 [type_class1], ...column_nameN |\n\
118+
funcname(column_name1, ...) [type_class] );"},
106119
{"create operator",
107120
"create a user-defined operator",
108121
"\
@@ -117,7 +130,7 @@ OR\n\
117130
"\
118131
\tCREATE RULE rule_name AS ON\n\
119132
\t{ SELECT | UPDATE | DELETE | INSERT }\n\
120-
\tTO object [WHERE qual]\n\
133+
\tTO object_name [WHERE qual]\n\
121134
\tDO [INSTEAD] [action|NOTHING|[actions]];"},
122135
{"create sequence",
123136
"create a new sequence number generator",
@@ -132,16 +145,16 @@ OR\n\
132145
{"create table",
133146
"create a new table",
134147
"\
135-
\tCREATE [TEMP] TABLE tablename\n\
136-
\t(colname1 type1 [DEFAULT expression] [NOT NULL], ...colnameN\n\
148+
\tCREATE [TEMP] TABLE table_name\n\
149+
\t(column_name1 type1 [DEFAULT expression] [NOT NULL], ...column_nameN\n\
137150
\t[[CONSTRAINT name] CHECK condition1, ...conditionN] )\n\
138-
\t[INHERITS (tablename1, ...tablenameN)\n\
151+
\t[INHERITS (table_name1, ...table_nameN)\n\
139152
;"},
140153
{"create trigger",
141154
"create a new trigger",
142155
"\
143156
\tCREATE TRIGGER trigger_name AFTER|BEFORE event1 [OR event2 [OR event3] ]\n\
144-
\tON tablename FOR EACH ROW|STATEMENT\n\
157+
\tON table_name FOR EACH ROW|STATEMENT\n\
145158
\tEXECUTE PROCEDURE func_name ([arguments])\n\
146159
\n\
147160
\teventX is one of INSERT, DELETE, UPDATE"},
@@ -167,27 +180,27 @@ OR\n\
167180
"create a view",
168181
"\
169182
\tCREATE VIEW view_name AS\n\
170-
\tSELECT [DISTINCT [ON colnameN]]\n\
171-
\texpr1 [AS colname1], ...exprN\n\
172-
\t[FROM from_list]\n\
183+
\tSELECT [DISTINCT [ON column_nameN]]\n\
184+
\texpr1 [AS column_name1], ...exprN\n\
185+
\t[FROM table_list]\n\
173186
\t[WHERE qual]\n\
174187
\t[GROUP BY group_list];"},
175188
{"declare",
176189
"set up a cursor",
177190
"\
178191
\tDECLARE cursorname [BINARY] CURSOR FOR\n\
179-
\tSELECT [DISTINCT [ON colnameN]]\n\
180-
\texpr1 [AS colname1], ...exprN\n\
181-
\t[FROM from_list]\n\
192+
\tSELECT [DISTINCT [ON column_nameN]]\n\
193+
\texpr1 [AS column_name1], ...exprN\n\
194+
\t[FROM table_list]\n\
182195
\t[WHERE qual]\n\
183196
\t[GROUP BY group_list]\n\
184197
\t[HAVING having_clause]\n\
185-
\t[ORDER BY colname1 [USING op1], ...colnameN]\n\
198+
\t[ORDER BY column_name1 [USING op1], ...column_nameN]\n\
186199
\t[ { UNION [ALL] | INTERSECT | EXCEPT } SELECT ...];"},
187200
{"delete",
188201
"delete tuples",
189202
"\
190-
\tDELETE FROM tablename [WHERE qual];"},
203+
\tDELETE FROM table_name [WHERE qual];"},
191204
{"drop",
192205
"Please be more specific:",
193206
"\
@@ -233,11 +246,11 @@ OR\n\
233246
{"drop table",
234247
"remove a table",
235248
"\
236-
\tDROP TABLE tablename1, ...tablenameN;"},
249+
\tDROP TABLE table_name1, ...table_nameN;"},
237250
{"drop trigger",
238251
"remove a trigger",
239252
"\
240-
\tDROP TRIGGER trigger_name ON tablename;"},
253+
\tDROP TRIGGER trigger_name ON table_name;"},
241254
{"drop type",
242255
"remove a user-defined base type",
243256
"\
@@ -271,11 +284,11 @@ OR\n\
271284
{"insert",
272285
"insert tuples",
273286
"\
274-
\tINSERT INTO tablename [(colname1, ...colnameN)]\n\
287+
\tINSERT INTO table_name [(column_name1, ...column_nameN)]\n\
275288
\tVALUES (expr1,..exprN) |\n\
276-
\tSELECT [DISTINCT [ON colnameN]]\n\
289+
\tSELECT [DISTINCT [ON column_nameN]]\n\
277290
\texpr1, ...exprN\n\
278-
\t[FROM from_clause]\n\
291+
\t[FROM table_list]\n\
279292
\t[WHERE qual]\n\
280293
\t[GROUP BY group_list]\n\
281294
\t[HAVING having_clause]\n\
@@ -291,7 +304,7 @@ OR\n\
291304
{"lock",
292305
"exclusive lock a table inside a transaction",
293306
"\
294-
\tLOCK [TABLE] tablename \n\
307+
\tLOCK [TABLE] table_name \n\
295308
\t[IN [ROW|ACCESS] [SHARE|EXCLUSIVE] | [SHARE ROW EXCLUSIVE] MODE];"},
296309
{"move",
297310
"move an cursor position",
@@ -319,15 +332,15 @@ TIMEZONE|XACTISOLEVEL|CLIENT_ENCODING|SERVER_ENCODING"},
319332
{"select",
320333
"retrieve tuples",
321334
"\
322-
\tSELECT [DISTINCT [ON colnameN]] expr1 [AS colname1], ...exprN\n\
323-
\t[INTO [TEMP] [TABLE] tablename]\n\
324-
\t[FROM from_list]\n\
335+
\tSELECT [DISTINCT [ON column_nameN]] expr1 [AS column_name1], ...exprN\n\
336+
\t[INTO [TEMP] [TABLE] table_name]\n\
337+
\t[FROM table_list]\n\
325338
\t[WHERE qual]\n\
326339
\t[GROUP BY group_list]\n\
327340
\t[HAVING having_clause]\n\
328341
\t[ { UNION [ALL] | INTERSECT | EXCEPT } SELECT ...]\n\
329-
\t[ORDER BY colname1 [ASC|DESC] [USING op1], ...colnameN ]\n\
330-
\t[FOR UPDATE [OF tablename...]]\n\
342+
\t[ORDER BY column_name1 [ASC|DESC] [USING op1], ...column_nameN ]\n\
343+
\t[FOR UPDATE [OF table_name...]]\n\
331344
\t[LIMIT count [OFFSET|, count]];"},
332345
{"set",
333346
"set run-time environment",
@@ -358,18 +371,18 @@ TIMEZONE|XACTISOLEVEL|CLIENT_ENCODING|SERVER_ENCODING"},
358371
{"truncate",
359372
"quickly removes all rows from a table",
360373
"\
361-
\tTRUNCATE TABLE tablename"},
374+
\tTRUNCATE TABLE table_name"},
362375
{"update",
363376
"update tuples",
364377
"\
365-
\tUPDATE tablename SET colname1 = expr1, ...colnameN = exprN\n\
366-
\t[FROM from_clause]\n\
378+
\tUPDATE table_name SET column_name1 = expr1, ...column_nameN = exprN\n\
379+
\t[FROM table_list]\n\
367380
\t[WHERE qual];"},
368381
{"vacuum",
369382
"vacuum the database, i.e. cleans out deleted records, updates statistics",
370383
"\
371384
\tVACUUM [VERBOSE] [ANALYZE] [table]\n\
372385
\tor\n\
373-
\tVACUUM [VERBOSE] ANALYZE [table [(colname1, ...colnameN)]];"},
386+
\tVACUUM [VERBOSE] ANALYZE [table [(column_name1, ...column_nameN)]];"},
374387
{NULL, NULL, NULL} /* important to keep a NULL terminator here!*/
375388
};

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy