From b0c451e145be23211dce0718cc63e632959591e8 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 5 Aug 2010 18:21:19 +0000
Subject: Remove the single-argument form of string_agg().  It added nothing
 much in functionality, while creating an ambiguity in usage with ORDER BY
 that at least two people have already gotten seriously confused by.  Also,
 add an opr_sanity test to check that we don't in future violate the newly
 minted policy of not having built-in aggregates with the same name and
 different numbers of parameters.  Per discussion of a complaint from Thom
 Brown.

---
 doc/src/sgml/func.sgml   | 12 ++++++------
 doc/src/sgml/syntax.sgml | 11 ++++++-----
 2 files changed, 12 insertions(+), 11 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 07ff132cbb5..b981ca7f920 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.523 2010/08/05 04:21:53 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.524 2010/08/05 18:21:17 tgl Exp $ -->
 
  <chapter id="functions">
   <title>Functions and Operators</title>
@@ -9782,7 +9782,7 @@ SELECT NULLIF(value, '(none)') ...
     <thead>
      <row>
       <entry>Function</entry>
-      <entry>Argument Type</entry>
+      <entry>Argument Type(s)</entry>
       <entry>Return Type</entry>
       <entry>Description</entry>
      </row>
@@ -9952,17 +9952,17 @@ SELECT NULLIF(value, '(none)') ...
         <primary>string_agg</primary>
        </indexterm>
        <function>
-         string_agg(<replaceable class="parameter">expression</replaceable> 
-                    [, <replaceable class="parameter">delimiter</replaceable> ] )
+         string_agg(<replaceable class="parameter">expression</replaceable>,
+                    <replaceable class="parameter">delimiter</replaceable>)
        </function>
       </entry>
       <entry>
-       <type>text</type>
+       <type>text</type>, <type>text</type>
       </entry>
       <entry>
        <type>text</type>
       </entry>
-      <entry>input values concatenated into a string, optionally with delimiters</entry>
+      <entry>input values concatenated into a string, separated by delimiter</entry>
      </row>
 
      <row>
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 16aa89f497f..ee2c5214aa9 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.149 2010/08/04 15:27:57 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.150 2010/08/05 18:21:17 tgl Exp $ -->
 
 <chapter id="sql-syntax">
  <title>SQL Syntax</title>
@@ -1583,16 +1583,17 @@ SELECT array_agg(a ORDER BY b DESC) FROM table;
    <para>
     When dealing with multiple-argument aggregate functions, note that the
     <literal>ORDER BY</> clause goes after all the aggregate arguments.
-    For example, this:
+    For example, write this:
 <programlisting>
 SELECT string_agg(a, ',' ORDER BY a) FROM table;
 </programlisting>
     not this:
 <programlisting>
-SELECT string_agg(a ORDER BY a, ',') FROM table;  -- not what you want
+SELECT string_agg(a ORDER BY a, ',') FROM table;  -- incorrect
 </programlisting>
-    The latter syntax will be accepted, but <literal>','</> will be
-    treated as a (useless) sort key.
+    The latter is syntactically valid, but it represents a call of a
+    single-argument aggregate function with two <literal>ORDER BY</> keys
+    (the second one being rather useless since it's a constant).
    </para>
 
    <para>
-- 
cgit v1.2.3