🌐 AI搜索 & 代理 主页
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)