Incorrect parameter name for CreateTopology

[dbaston]

I tried to create a topology with keyword arguments, following the parameter names in the docs:

postgres=# select topology.CreateTopology('tiger_mcds', srid := 4326, tolerance := 1e-6, hasz := false);
ERROR:  function topology.createtopology(unknown, srid => integer, tolerance => numeric, hasz => boolean) does not exist

The parameter referred to in the docs as "tolerance" is known as "prec" in the SQL function. I'm not sure what the best fix is — redefine the function to match the docs (I think "tolerance" is a better name) or change the docs to match the existing function?

[strk]

It's easier to fix the documentation, in general, as CREATE OR REPLACE FUNCTION cannot change parameter names. I'm surprised this case was not caught by garden test, as I thought it did try the named parameter syntax for every documented function.

[dbaston]

Looks like this isn't an isolated case…in ST_GetFaceEdges, both parameter names differ from the docs. Do you think it's worth standardizing these for 2.3 and updating the docs to match? atopology vs toponame, aface vs face_id, etc. I'm delving into this for the first time today, so these are just some things that stick out as a new user.

[strk]

Honestly I'd prefer to keep things simple.

Remember that any parameter name change would require adding the old function name into topology_drop_before.sql.in, which currently only has 2 entries and I would have avoided it completely (was added by Regina)

Also if anyone would really be using parameter names. changing them would require changing calling code (its an effective API breakage).

Personally I don't use or recommend using parameter names to my customers so my main concern is the maintainance of the upgrade procedure. To me, fixing the dox is the simplest and safer way to deal with this.

[strk]

Regina can you think of a way to automate testing for these matching ? Maybe from the garden test ?

[robe]

I'd have to be figure out a way to trap the error. I can revise to use named args. Maybe we should have that as a separate test.

Although I tend to avoid using named args, they come in really handy with raster since you can override a default without having to set all the default values before it. In these cases I tend to use a mix of named and unnamed arguments for optimal laziness.

[robe]

In 15246:

Incorrect parameter name for CreateTopology
references #3509 for 2.3.1

[robe]

In 15247:

Incorrect parameter name for CreateTopology
references #3509 for 2.4.0 (trunk)

[robe]

In 15248:

Incorrect parameter name for CreateTopology
closes #3509 for 2.2.4