Documenting parameters

[cvvergara]

From RFC 3 and following #109
The unwritten story trying to make it written

---

Other documentation

PostgreSQL

Network functions are unnamed
String functions some look that they are named like

concat_ws(sep text, str "any" [, str "any" [, ...] ])

But actually is unnamed:

SELECT  proargnames from pg_proc where proname ='concat_ws';
 proargnames 
-------------
 
(1 row)

Notice that in the documentation they come as: Pseudo name type like sep text

PostGIS

ST_Expand from PostGIS

function	comment
geometry ST_Expand(geometry geom, float units_to_expand);	look like named parameters but they are not
geometry ST_Expand(geometry geom, float dx, float dy, float dz=0, float dm=0);	named parameters
box2d ST_Expand(box2d box, float units_to_expand);	look like named parameters but they are not
box2d ST_Expand(box2d box, float dx, float dy);	named parameters
box3d ST_Expand(box3d box, float units_to_expand);	look like named parameters but they are not
box3d ST_Expand(box3d box, float dx, float dy, float dz=0);	named parameters

Some are named, some are not named, but as you see above, all look like they have names.

SELECT  proname, proargnames from pg_proc where proname LIKE 'st_expand';
  proname  |    proargnames     
-----------+--------------------
 st_expand | 
 st_expand | {box,dx,dy}
 st_expand | 
 st_expand | {box,dx,dy,dz}
 st_expand | 
 st_expand | {geom,dx,dy,dz,dm}
(6 rows)

Notice that in the documentation they come as: type Pseudo name like box2d box

Other languages

In PostgreSQL the unnamed parameters are positional, and the named parameters can change position, but once you use a named parameter the rest of the parameters must be named. The order of these arguments matters when they’re passed positionally:

• C++ all functions have positional parameters

Currently

On v3.0 dijkstra as first glance the parameters look like they are all named:

pgr_dijkstra(edges_sql, start_vid,  end_vid  [, directed])

Strictly speaking as we don't have names on compulsory parameters:

pgr_dijkstra(text, bigint,  bigint  [,  directed BOOLEAN default = true])

But that gives less information of what is each one.

On v3.1 dijkstra there is a first attempt to make it look that is not a named parameter, at least on the edges sql:

pgr_dijkstra(Edges SQL, start_vid,  end_vid  [, directed])

Note that pgRouting does not use the types on the signatures. The reason for that is that the parameters become so complex that they need a deep explanation. For example: factor on the aStar Family of functions.

A possibility for a future release (like 3.2) is to have:

pgr_dijkstra(Edges SQL, start vid,  end vid  [, directed])

or

pgr_dijkstra(Edges SQL, Start VID,  End VID  [, directed])

or

pgr_dijkstra(Edges SQL, Start vid,  End vid  [, directed])

or

pgr_dijkstra(Edges SQL, Start vertex,  End vertex [, directed])