Confused on the documentation

[MarPetra]

I am standarizing documentation and I get confused because the parameters and the result columns have the same names , for example:

pgr_aStar(edges_sql, start_vid,  end_vid  [, directed] [, heuristic] [, factor] [, epsilon])
pgr_aStar(edges_sql, start_vid,  end_vids [, directed] [, heuristic] [, factor] [, epsilon])
pgr_aStar(edges_sql, start_vids, end_vid  [, directed] [, heuristic] [, factor] [, epsilon])
pgr_aStar(edges_sql, start_vids, end_vids [, directed] [, heuristic] [, factor] [, epsilon])
RETURNS SET OF (seq, path_seq [, start_vid] [, end_vid], node, edge, cost, agg_cost)

When I work on the individual function and I double check the summary I get confused because, for example, they have the start_vid in the function call but not on the result.

[cvvergara]

• If the singular is in the function call then the singular is not on the results
• If the plural is in the function call then the singular is on the results In this example:

pgr_aStar(edges_sql, start_vid, end_vids [, directed] [, heuristic] [, factor] [, epsilon])
RETURNS SET OF (seq, path_seq, end_vid, node, edge, cost, agg_cost)
OR EMPTY SET

• the singular start_vid is in the function call so its not on the results
• the plural end_vids is in the function call so the singular end_vid is on the results

[cvvergara]

Internally, even that in postgreSQL has named parameters, where the name can be used within a function, because of the name collision: we are using unnamed parameters on the function signatures and the parameters are named when they are optional

[cvvergara]

if the names were different then It would be possible to have all the functions return all the columns, for example:

pgr_aStar(edges_sql, start_vid,  end_vid  [, directed] [, heuristic] [, factor] [, epsilon])
pgr_aStar(edges_sql, start_vid,  end_vids [, directed] [, heuristic] [, factor] [, epsilon])
pgr_aStar(edges_sql, start_vids, end_vid  [, directed] [, heuristic] [, factor] [, epsilon])
pgr_aStar(edges_sql, start_vids, end_vids [, directed] [, heuristic] [, factor] [, epsilon])
RETURNS SET OF (seq, path_seq, from_vid, to_vid, node, edge, cost, agg_cost)

[cvvergara]

other example:

pgr_aStar(edges_sql, from_vid,  to_vid  [, directed] [, heuristic] [, factor] [, epsilon])
pgr_aStar(edges_sql, from_vid,  to_vids [, directed] [, heuristic] [, factor] [, epsilon])
pgr_aStar(edges_sql, from_vids, to_vid  [, directed] [, heuristic] [, factor] [, epsilon])
pgr_aStar(edges_sql, from_vids, to_vids [, directed] [, heuristic] [, factor] [, epsilon])
RETURNS SET OF (seq, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)

In this example because anyway, internally we are not using named parameters on the compulsory parameters, it will break less code.

[MarPetra]

I found an error on prg_bdDijkstraCost.

In the summary:

pgr_bdDijkstraCost(edges_sql, start_vid,  end_vid  [, directed])
pgr_bdDijkstraCost(edges_sql, start_vid,  end_vids [, directed])
pgr_bdDijkstraCost(edges_sql, start_vids, end_vid  [, directed])
pgr_bdDijkstraCost(edges_sql, start_vids, end_vids [, directed])
RETURNS SET OF (start_vid, end_vid, agg_cost)
OR EMPTY SET

The one to one function has a mistake:

pgr_bdDijkstraCost(edges_sql, start_vid, end_vid [, directed])
RETURNS SET OF (seq, path_seq, node, edge, cost, agg_cost)
OR EMPTY SET

Do I fix like this?:

pgr_bdDijkstraCost(edges_sql, start_vid,  end_vid  [, directed])
RETURNS SET OF (agg_cost)
OR EMPTY SET

Based on a previous comment, this are the reasons I deduce:

• Because on the function call start_vid is in singular, then it doesn't show on the result
• Because on the function call end_vid is in singular, then it doesn't show on the result

[cvvergara]

The correct fix, on all prg_bdDijkstraCost signatures is

RETURNS SET OF (start_vid, end_vid, agg_cost)

---

Actually, that is a perfect example where internally we have to use unnamed parameters because of name collisions https://github.com/pgRouting/pgrouting/blob/develop/sql/bdDijkstra/bdDijkstraCost.sql

That said, this would be the "correct" summary:

pgr_bdDijkstraCost(TEXT, BIGINT,  BIGINT  [, directed])
pgr_bdDijkstraCost(TEXT, BIGINT,  BIGINT[] [, directed])
pgr_bdDijkstraCost(TEXT, BIGINT[], BIGINT  [, directed])
pgr_bdDijkstraCost(TEXT, BIGINT[], BIGINT[] [, directed])
RETURNS SET OF (start_vid, end_vid, agg_cost)
OR EMPTY SET

because the parameters don't have names But then again that does not provide at first glance "useful" information

What if ?

Because the parameters are unnamed, this summary might be an option, that at first glance has "useful" information and does not have the name collision

pgr_bdDijkstraCost(edges_sql, from_vid,  to_vid  [, directed])
pgr_bdDijkstraCost(edges_sql, from_vid,  to_vids [, directed])
pgr_bdDijkstraCost(edges_sql, from_vids, to_vid  [, directed])
pgr_bdDijkstraCost(edges_sql, from_vids, to_vids [, directed])
RETURNS SET OF (start_vid, end_vid, agg_cost)
OR EMPTY SET

Because we are using unnamed parameters in the majority of the functions for 3.0 aka on version 2.6, the majority of the functions are proposed or experimental, Like its the case of pgr_bdDijkstraCost then doing the name change on the documentation would avoid name collision on the documentation

[MarPetra]

Because pgr_bdDijkstraCost in version 2.6 is proposed, can I use:

pgr_bdDijkstraCost(edges_sql, from_vid,  to_vid  [, directed])
pgr_bdDijkstraCost(edges_sql, from_vid,  to_vids [, directed])
pgr_bdDijkstraCost(edges_sql, from_vids, to_vid  [, directed])
pgr_bdDijkstraCost(edges_sql, from_vids, to_vids [, directed])
RETURNS SET OF (start_vid, end_vid, agg_cost)
OR EMPTY SET

? and, what is on that link, I don't need to fix it, right?

[cvvergara]

Actually the same usage of from_vid etc would apply to all the bdDijkstra functions https://github.com/pgRouting/pgrouting/blob/develop/sql/bdDijkstra/bdDijkstra.sql they all have unnamed parameters on the compulsory parameters and named parameters on the optional parameters.

About the code links, they are informational, you don't need to touch those files

[cvvergara]

If you can work, "Cost" category

• pgr_astarCost
• pgr_bdAstarCost
• pgr_bdDijkstraCost
• pgr_djkstraCost

Standarize that category

Make the summaries look like (using as example pgr_bdDijkstraCost)

pgr_bdDijkstraCost(edges_sql, from_vid,  to_vid  [, directed])
pgr_bdDijkstraCost(edges_sql, from_vid,  to_vids [, directed])
pgr_bdDijkstraCost(edges_sql, from_vids, to_vid  [, directed])
pgr_bdDijkstraCost(edges_sql, from_vids, to_vids [, directed])
RETURNS SET OF (start_vid, end_vid, agg_cost)
OR EMPTY SET