[pgrouting-dev] Signature documentation

pgRouting pgrouting-dev
1 
Hello all:

I am working on the documention.

I have this internal conflict when talking about signatures:
(1)
    pgr_foo( edges_sql,  points_sql,  start_pid,  K,
          directed := true,  heap_paths := false,  driving_side := 'b',  details := false)
    RETURNS SET OF (seq, path_id, path_seq, node, edge, cost, agg_cost)
VS (2)
    pgr_foo(TEXT edges_sql, TEXT points_sql, BIGINT start_pid, INTEGER K,
         BOOLEAN directed := true, BOOLEAN heap_paths := false, CHAR driving_side := 'b', BOOLEAN details := false)
   RETURNS SET OF (INTEGER seq, INTEGER path_id, INTEGER path_seq, BIGINT node, BIGINT edge, FLOAT cost, FLOAT agg_cost)

The types of the variables are always explained later.

So my conflict is:
The one hat has the types in the signature is almost the correct one, but there are so many parameters that makes it
difficult to understand and of course, postgresql types are after the name of the variable, in C/C++ the types are before.

So, bottom line: none of them is correct 
(1) looks more readable
(2) is what we have being using

Documenting takes a lot of time, (specially if you want to leave the documentation in such a way that doesn't have to be "fixed" later)

I would really appreciate a comment on this topic.

Vicky
2

Forgot to mention,

Any of the two ways of writing it will make me go check the whole documentation to standardize it to the one chosen.
But I can focus on the functions of 2.1 and the near-future-2.2-once-documentation-is-finished.

Vicky

From: vicky_vergara@hotmail.com
To: pgrouting-dev@lists.osgeo.org
Date: Wed, 24 Feb 2016 13:45:20 -0600
Subject: [pgrouting-dev] Signature documentation

Hello all:

I am working on the documention.

I have this internal conflict when talking about signatures:
(1)
    pgr_foo( edges_sql,  points_sql,  start_pid,  K,
          directed := true,  heap_paths := false,  driving_side := 'b',  details := false)
    RETURNS SET OF (seq, path_id, path_seq, node, edge, cost, agg_cost)
VS (2)
    pgr_foo(TEXT edges_sql, TEXT points_sql, BIGINT start_pid, INTEGER K,
         BOOLEAN directed := true, BOOLEAN heap_paths := false, CHAR driving_side := 'b', BOOLEAN details := false)
   RETURNS SET OF (INTEGER seq, INTEGER path_id, INTEGER path_seq, BIGINT node, BIGINT edge, FLOAT cost, FLOAT agg_cost)

The types of the variables are always explained later.

So my conflict is:
The one hat has the types in the signature is almost the correct one, but there are so many parameters that makes it
difficult to understand and of course, postgresql types are after the name of the variable, in C/C++ the types are before.

So, bottom line: none of them is correct 
(1) looks more readable
(2) is what we have being using

Documenting takes a lot of time, (specially if you want to leave the documentation in such a way that doesn't have to be "fixed" later)

I would really appreciate a comment on this topic.

Vicky

_______________________________________________ pgrouting-dev mailing list pgrouting-dev@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/pgrouting-dev