Comments on Postgis Functions

[dane.springmeyer]

This is a small feature request / question.

I'm curious if there has been any thought about adding comments to postgis functions?

I've written several sql functions to take advantage of function comments (when they exist) which are included in this thread:  http://postgis.refractions.net/pipermail/postgis-devel/2008-April/002989.html

I've also started writing a python script which parses out all the documentation notes in chapter six of the official documentation using this file:  http://svn.refractions.net/postgis/trunk/doc/postgis.xml.

The idea is to insert them as database comments. Whenever the official documentation is updated this script could be re-run to regenerate the .sql to attach comments.

If this is of interest to the developers I would be happy to work on getting the function inserts working (I assume that proper matching could be tricky).

A user would then be able to do add them like: $ psql -f postgis_func_comments.sql -d your_spatial_database

And in the psql interpreter a user would not only be able to say...

wind=# wind=# \df *ewkt*

List of functions

Schema | Name | Result data type | Argument data types

---

public | asewkt | text | geometry public | geomfromewkt | geometry | text public | st_asewkt | text | geometry public | st_geomfromewkt | geometry | text

But also say, for example, 'select postgis_help('ewkt');' be able to say...

wind=# select * from postgis_help('ewkt');

usage | comments

---

asewkt(geometry) | Deprecated Function (use ST_AsEWKT instead): Returns a Geometry in EWKT format (as text). geomfromewkt(text) | Deprecated Function(use ST_GeomFromEWKT instead): Makes a Geometry from EWKT. st_asewkt(geometry) | Returns a Geometry in EWKT format (as text). st_geomfromewkt(text) | Makes a Geometry from EWKT.

(4 rows)

Or even:

wind=# \dd *ewkt*

Object descriptions

Schema | Name | Object | Description

---

public | asewkt | function | Deprecated Function (use ST_AsEWKT instead): Returns a Geometry in EWKT format (as text). public | geomfromewkt | function | Deprecated Function(use ST_GeomFromEWKT instead): Makes a Geometry from EWKT. public | st_asewkt | function | Returns a Geometry in EWKT format (as text). public | st_geomfromewkt | function | Makes a Geometry from EWKT.

[dane.springmeyer]

Two recent threads on postgis-users have hit upon the importance of function comments:

•  http://postgis.refractions.net/pipermail/postgis-users/2008-June/020283.html
•  http://postgis.refractions.net/pipermail/postgis-users/2008-June/020279.html

Since originally posting this issue I have come to understand two somewhat messy issues:

1) The function names in the postgis.xml docbook use different terms for the input data types than the actual functions inserted with lwpostgis.sql

ie. the docbook has ST_Buffer(geometry, double, [integer]) whereas vs lwpostgis.sql includes buffer(geometry, double precision), buffer(geometry, double precision, integer), st_buffer(geometry, double precision), and st_buffer(geometry, double precision, integer)

2) The postgis.xml docbook is not valid xml in svn trunk and has a number of pecularities that make it less than straightfoward to parse like nested <link> elements inside <para> elements and lack of convention in listing functions without specific docs, sometimes saying <term> 1, 2<term> and in other cases saying <term>1</term> <term>2</term><para>meta</para>

Nevertheless I have a functional script ready for testing and (much) refinement. The script attempts to match all OpenGIS PostGIS functions within Chapter 6 of the postgis.xml docbook with existing functions in a postgis enabled db, and outputs a sql script to insert function comments.

The sample script ('postgis_function_commentor.py') and a sample output ('insert_function_comments.sql') are attached for reference.

This was created with an 8.2 database, so any relatively new functions will have been missed.

There are numerous way to go about improving this and catching errors. Feel free to post ideas and I will try to integration them.

[pramsey]

<i>(No comment was entered for this change.)</i>

[robe]

Committed xsl file to new doc/xsl folder that autogenerates sql comment insert statements using current reference_new.xml. Has not been integrated into build. Waiting for Mark to approve. Only relies on xsltproc so no python dependency.

Eventually will try to integrate Dane's sql help module to show extended help.

[dane.springmeyer]

Awesome. Can't wait to test.

[dane.springmeyer]

Regina,

I'm stuck momentarily trying to rebuild my libxslt since I got this error with your command to build the sql:

springmeyer:doc spring$ xsltproc -o postgis_comments.sql xsl/postgis_comments.sql.xsl reference_new.xml compilation error: file xsl/postgis_comments.sql.xsl line 2 element stylesheet xsl:version: only 1.0 features are supported

So, I tried the 'postgis_comments.sql' you posted to postgis-dev and it looks good.

However, I did notice a few things:

1) There are windows line endings that show up as 'rs in my psql terminal (see below, but which won't be a problem I figure when I can build it myself).

2) In the example below shouldn't the first ST_AsKML(geometry ) entry (as opposed to ST_AsKML(geometry , integer )) not list the Second argument explanation in the comments?

beaver=# \dd *kml*

Object descriptions

Schema | Name | Object | Description

---

public | st_askml | function | args: g1 - Return the geometry as a KML element. Second argument may be\r

: used to reduce the maximum number of significant digits used in\r : output (defaults to 15).

public | st_askml | function | args: g1, max_num_decimal_digits - Return the geometry as a KML element. Second argument may be\r

: used to reduce the maximum number of significant digits used in\r : output (defaults to 15).

[kneufeld]

Yeah, I got the same error using xsltproc. Changing the second line to version 1.0 solved the compile problem for me. -- Kevin

[robe]

Sorry about the 2.0. I have changed it to 1.0. I was meaning to use the replace function introduced in xsl 2.0 and then realized we weren't using 2.0 and my IDE parser wasn't using 2.0 either, so I fell on the 1.0 replace template hack, but forgot to change the header back to 1.0.

Regarding the ST_AsKML issue. Its a problem with all our functions that have more than one function equivalent. We have one synopsis for the whole entry so I am copying the definition part from the synopsis - so is always the same for all. Hmm I was thinking we probably should have separate definitions for each function, but thought that would be both more effort for documentors and not sure if its even doable to stuff the comment in with the function prototype. So sort of settled on having the comment try to cover all permutations of functions in some shape or form.

The ST_GeoJSON one would get especially hairy since there are I htink 7 protos of that.

[robe]

I think I can close this out for now and reopen a new one if we decide to go with a full-blown help thingy. I think I covered most of the important descriptions in the postgis_comments.sql file.

[dane.springmeyer]

Yes, closing sounds great. Regina, the postgis_comments.sql is awesome.

-dane

[dane.springmeyer]

 http://postgis.googlecode.com/issues/attachment?aid=-996540309021860253&name=postgis_function_commentor.py

[robe]

Thanks Dane - for the next iteration now that we have some functions flagged as to whether they support 3D or circular - I was thinking of stuffing a

(3C), (3), (3C) in there somewhere in the comments right after the args - 3 for 3d support and C for Circular string support. That way I won't have to look back at the docs to know what functions work with what. That seems like a fairly trivial change to the xsl transforms. But guess that can wait for 1.4.

[dane.springmeyer]

 http://postgis.googlecode.com/issues/attachment?aid=8992769894183517994&name=insert_function_comments.sql