[postgis-devel] Adding argument names to PostGIS functions

[Mike Toews]

Last month I asked pgsql-hackers[1] about the use of argument names
for function definitions. To summarize, I see there are two advantages
for using argument names for function
definitions: to add run-time or extra documentation for the
parameters, and allow named notation (where applicable). There was one
"0+" response from a pgsql-hacker, and I may follow-up and look into
providing a patch for pg_proc.h in the future.

Would the PostGIS devs be open to a patch to include argument names
for parameters for functions in postgis.sql.in.c and
geography.sql.in.c? I haven't prepared any work yet, as I would like
to ask here for feedback before preparing a patch. The names for
argname would be determined from the "SQL prototypes" in the
documentation, if available. As for functions with only one
non-optional argument (e.g.,
http://www.postgis.org/docs/ST_Reverse.html with prototype: "geometry
ST_Reverse(geometry g1);"), should I bother? My sense is "no", as I
don't see any added value, but I'd like to know how others feel.

As it stands in svn-trunk, most plpgsql functions already have
argnames defined. There are a few older functions, like
"ST_find_extent" that look dated with "alias for $1", $2, etc. It is
mostly the C internal functions where I'd be adding argnames from the
documentation, such as ST_MakePoint(float8, float8, float8, float8):

CREATE OR REPLACE FUNCTION ST_MakePoint(x float8, y float8, z float8, m float8)
    RETURNS geometry
    AS 'MODULE_PATHNAME', 'LWGEOM_makepoint'
    LANGUAGE 'C' IMMUTABLE STRICT;

-- or: ST_SnapToGrid(geometry, float8, float8, float8, float8):
CREATE OR REPLACE FUNCTION ST_SnapToGrid(geomA geometry, originX
float8, originY float8, sizeX float8, sizeY float8)
    RETURNS geometry
    AS 'MODULE_PATHNAME', 'LWGEOM_snaptogrid'
    LANGUAGE 'C' IMMUTABLE STRICT;

I'm not considering adding argument defaults and removing duplicate
overloaded functions at this stage.

Let me know your input, particularly any concerns that could
potentially be unintentionally introduced, or if this is unwanted
bloat.

-Mike

[1] http://archives.postgresql.org/pgsql-hackers/2011-07/msg01010.php