From bb53b72c00cce20320784c8ff987b1faa54959e3 Mon Sep 17 00:00:00 2001
From: Regina Obe <lr@pcorp.us>
Date: Sat, 27 Feb 2016 08:05:34 +0000
Subject: [PATCH] use a new arg identifier winset for window functions. Update
 window functions to be flagged as taking input geometry winset Update
 templste.xml (to instruct how to flag window and aggregate functions) Update
 the comments generation to handle the new geometry winset type arg Closes
 #3474 Mark ST_ClusterWithin and ST_ClusterIntersecting as taking geometry set
 (so flagged as aggregates) Closes #3476

git-svn-id: http://svn.osgeo.org/postgis/trunk@14711 b70326c6-7e19-0410-871a-916f4a2858ee
---
 doc/reference_measure.xml        |  8 ++++----
 doc/template.xml                 | 18 +++++++++++++++++-
 doc/xsl/postgis_aggs_mm.xml.xsl  | 29 +++++++++++++++++++++++++++++
 doc/xsl/postgis_comments.sql.xsl |  3 ++-
 4 files changed, 52 insertions(+), 6 deletions(-)

diff --git a/doc/reference_measure.xml b/doc/reference_measure.xml
index d1dbf6d46..78aa03bd6 100644
--- a/doc/reference_measure.xml
+++ b/doc/reference_measure.xml
@@ -1062,7 +1062,7 @@ SELECT ST_AsText(
 		  <funcprototype>
 			<funcdef>integer <function>ST_ClusterDBSCAN</function></funcdef>
 
-			<paramdef><type>geometry </type>
+			<paramdef><type>geometry winset </type>
 			<parameter>geom</parameter></paramdef>
 
 			<paramdef><type>float8 </type>
@@ -1130,7 +1130,7 @@ GROUP BY cid;
         <funcsynopsis>
           <funcprototype>
             <funcdef>geometry[] <function>ST_ClusterIntersecting</function></funcdef>
-            <paramdef><type>geometry </type> <parameter>g</parameter></paramdef>
+            <paramdef><type>geometry set</type> <parameter>g</parameter></paramdef>
           </funcprototype>
         </funcsynopsis>
       </refsynopsisdiv>
@@ -1187,7 +1187,7 @@ GEOMETRYCOLLECTION(LINESTRING(6 6,7 7))
 		  <funcprototype>
 			<funcdef>integer <function>ST_ClusterKMeans</function></funcdef>
 
-			<paramdef><type>geometry </type>
+			<paramdef><type>geometry winset </type>
 			<parameter>geom</parameter></paramdef>
 
 			<paramdef><type>integer </type>
@@ -1235,7 +1235,7 @@ FROM parcels;
         <funcsynopsis>
           <funcprototype>
             <funcdef>geometry[] <function>ST_ClusterWithin</function></funcdef>
-            <paramdef><type>geometry </type> <parameter>g</parameter></paramdef>
+            <paramdef><type>geometry set </type> <parameter>g</parameter></paramdef>
             <paramdef><type>float8 </type> <parameter>distance</parameter></paramdef>
           </funcprototype>
         </funcsynopsis>
diff --git a/doc/template.xml b/doc/template.xml
index 8f05ad5ec..56254df3a 100644
--- a/doc/template.xml
+++ b/doc/template.xml
@@ -14,7 +14,7 @@
         <paramdef><type>geometry </type> <parameter>g2</parameter></paramdef>
       </funcprototype>
 
-      <!-- an optional second method prototype -->
+      <!-- an optional second method prototype with default args -->
       <funcprototype>
         <funcdef>boolean <function>ST_MyMethod</function></funcdef>
         <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
@@ -23,6 +23,22 @@
         
         <paramdef choice="opt"><type>varchar </type> <parameter>myparam=the_default_value</parameter></paramdef>
       </funcprototype>
+      
+      <!-- example of a spatial aggregate prototype -->
+      <!-- If your function is an aggregate, the input for the
+        set part eg. set of geometries, should be of type geometry set/geometry set instead of geometry/geography -->
+      <funcprototype>
+        <funcdef>geometry <function>ST_MyMethod</function></funcdef>
+        <paramdef><type>geometry set </type> <parameter>g1</parameter></paramdef>
+      </funcprototype>
+      
+      <!-- example of a spatial window function prototype -->
+      <!-- If your function is window function, the input for the
+        set part (the input to the window) eg. set of geometries, should be of type geometry winset/geometry winset instead of geometry/geography -->
+      <funcprototype>
+        <funcdef>geometry <function>ST_MyMethod</function></funcdef>
+        <paramdef><type>geometry winset </type> <parameter>g1</parameter></paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
diff --git a/doc/xsl/postgis_aggs_mm.xml.xsl b/doc/xsl/postgis_aggs_mm.xml.xsl
index f43d65bd3..92f327527 100644
--- a/doc/xsl/postgis_aggs_mm.xml.xsl
+++ b/doc/xsl/postgis_aggs_mm.xml.xsl
@@ -44,6 +44,35 @@
 			</xsl:for-each>
 			</itemizedlist>
 		</sect1>
+		
+		<sect1 id="PostGIS_Window_Functions">
+			<title>PostGIS Window Functions</title>
+			<para>The functions given below are spatial window functions provided with PostGIS that can be used just like any other sql window function such as row_numer(), lead(), lag(). All these require an SQL OVER() clause.</para>
+			<itemizedlist>
+			<!-- Pull out the purpose section for each ref entry and strip whitespace and put in a variable to be tagged unto each function comment  -->
+			<xsl:for-each select='//refentry'>
+				<xsl:sort select="refnamediv/refname"/>
+				<xsl:variable name='comment'>
+					<xsl:value-of select="normalize-space(translate(translate(refnamediv/refpurpose,'&#x0d;&#x0a;', ' '), '&#09;', ' '))"/>
+				</xsl:variable>
+				<xsl:variable name="refid">
+					<xsl:value-of select="@id" />
+				</xsl:variable>
+				<xsl:variable name="refname">
+					<xsl:value-of select="refnamediv/refname" />
+				</xsl:variable>
+
+			<!-- For each function prototype if it takes a geometry set then catalog it as an aggregate function  -->
+				<xsl:for-each select="refsynopsisdiv/funcsynopsis/funcprototype">
+					<xsl:choose>
+						<xsl:when test="contains(paramdef/type,' winset')">
+							 <listitem><simpara><link linkend="{$refid}"><xsl:value-of select="$refname" /></link> - <xsl:value-of select="$comment" /></simpara></listitem>
+						</xsl:when>
+					</xsl:choose>
+				</xsl:for-each>
+			</xsl:for-each>
+			</itemizedlist>
+		</sect1>
 
 		<sect1 id="PostGIS_SQLMM_Functions">
 			<title>PostGIS SQL-MM Compliant Functions</title>
diff --git a/doc/xsl/postgis_comments.sql.xsl b/doc/xsl/postgis_comments.sql.xsl
index c0987a406..9921e33a7 100644
--- a/doc/xsl/postgis_comments.sql.xsl
+++ b/doc/xsl/postgis_comments.sql.xsl
@@ -37,10 +37,11 @@
 		</xsl:choose>
 <!-- For each function prototype generate the DDL comment statement
 	If its input is a geometry set - we know it is an aggregate function rather than a regular function 
+	If its input is a geometry winset we know it is a window function but comment signature of those are the same just have to strip off the winset
 	Do not output OUT params since they define output rather than act as input and do not put a comma after argument just before an OUT parameter -->
 		<xsl:for-each select="refsynopsisdiv/funcsynopsis/funcprototype">
 COMMENT ON <xsl:choose><xsl:when test="contains(paramdef/type,'geometry set')">AGGREGATE</xsl:when><xsl:otherwise>FUNCTION</xsl:otherwise></xsl:choose><xsl:text> </xsl:text> <xsl:value-of select="funcdef/function" />(<xsl:for-each select="paramdef"><xsl:choose><xsl:when test="count(parameter) &gt; 0"> 
-<xsl:choose><xsl:when test="contains(parameter,'OUT')"></xsl:when><xsl:when test="contains(type,'geometry set')">geometry</xsl:when><xsl:otherwise><xsl:value-of select="type" /></xsl:otherwise></xsl:choose><xsl:if test="position()&lt;last() and not(contains(parameter,'OUT')) and not(contains(following-sibling::paramdef[1],'OUT'))"><xsl:text>, </xsl:text></xsl:if></xsl:when>
+<xsl:choose><xsl:when test="contains(parameter,'OUT')"></xsl:when><xsl:when test="contains(type,'geometry set')">geometry</xsl:when><xsl:when test="contains(type,'geometry winset')">geometry</xsl:when><xsl:when test="contains(type,'geography winset')">geography</xsl:when><xsl:otherwise><xsl:value-of select="type" /></xsl:otherwise></xsl:choose><xsl:if test="position()&lt;last() and not(contains(parameter,'OUT')) and not(contains(following-sibling::paramdef[1],'OUT'))"><xsl:text>, </xsl:text></xsl:if></xsl:when>
 </xsl:choose></xsl:for-each>) IS '<xsl:call-template name="listparams"><xsl:with-param name="func" select="." /></xsl:call-template> <xsl:value-of select='$comment' />';
 			</xsl:for-each>
 		</xsl:for-each>
-- 
2.40.0