[withPointsDD][doc] Updating v3.6.0 release notes and fixing doc

squarege · Aug 21, 2023 · ff0889d · ff0889d
1 parent a044186
commit ff0889d
Show file tree

Hide file tree

Showing 3 changed files with 119 additions and 70 deletions.
diff --git a/NEWS b/NEWS
@@ -3,7 +3,7 @@ pgRouting 3.6.0 Release Notes
 
 **Official functions changes**
 
-* `2516 <https://github.com/pgRouting/pgrouting/pull/2516>` Standarize output
+* [#2516](https://github.com/pgRouting/pgrouting/pull/2516) Standarize output
   pgr_aStar
 
   * Standarizing output columns to |short-generic-result|
@@ -12,7 +12,7 @@ pgRouting 3.6.0 Release Notes
     * ``pgr_aStar`` (`One to Many`) added ``end_vid`` column.
     * ``pgr_aStar`` (`Many to One`) added ``start_vid`` column.
 
-* `2523 <https://github.com/pgRouting/pgrouting/pull/2523>` Standarize output
+* [#2523](https://github.com/pgRouting/pgrouting/pull/2523) Standarize output
   pgr_bdAstar
 
   * Standarizing output columns to |short-generic-result|
@@ -21,27 +21,46 @@ pgRouting 3.6.0 Release Notes
     * ``pgr_bdAstar`` (`One to Many`) added ``end_vid`` column.
     * ``pgr_bdAstar`` (`Many to One`) added ``start_vid`` column.
 
+**Proposed functions changes**
+
+* [#2544](https://github.com/pgRouting/pgrouting/pull/2544) Standarize output and modifying signature
+  pgr_withPointsDD
+
+  * New proposed signatures: ``driving side`` parameter changed from optional to compulsory
+
+    * ``pgr_withPointsDD`` (`Single vertex`)
+    * ``pgr_withPointsDD`` (`Multiple vertices`)
+
+  * Deprecated signatures:
+
+    * ``pgr_withpointsdd(text,text,bigint,double precision,boolean,character,boolean)``
+    * ``pgr_withpointsdd(text,text,anyarray,double precision,boolean,character,boolean,boolean)``
+
+  * Standarizing output columns to |result-bfs|
+
+    * ``pgr_withPointsDD`` (`Single vertex`) added ``depth`` and ``start_vid`` column.
+    * ``pgr_withPointsDD`` (`Multiple vertices`) added ``depth`` column.
 
 **C/C++ code enhancements**
 
-* `2504 <https://github.com/pgRouting/pgrouting/pull/2504>` To C++ pg data get,
+* [#2504](https://github.com/pgRouting/pgrouting/pull/2504) To C++ pg data get,
   fetch and check.
 
   * Stopping support for compilation with MSVC.
 
-* `2505 <https://github.com/pgRouting/pgrouting/pull/2505>` Using namespace.
-* `2512 <https://github.com/pgRouting/pgrouting/pull/2512>` [Dijkstra] Removing
+* [#2505](https://github.com/pgRouting/pgrouting/pull/2505) Using namespace.
+* [#2512](https://github.com/pgRouting/pgrouting/pull/2512) [Dijkstra] Removing
   duplicate code on Dijkstra.
-* `2517 <https://github.com/pgRouting/pgrouting/pull/2517>` Astar code
+* [#2517](https://github.com/pgRouting/pgrouting/pull/2517) Astar code
   simplification.
-* `2521 <https://github.com/pgRouting/pgrouting/pull/2521>` Dijkstra code
+* [#2521](https://github.com/pgRouting/pgrouting/pull/2521) Dijkstra code
   simplification.
-* `2522 <https://github.com/pgRouting/pgrouting/pull/2522>` bdAstar code
+* [#2522](https://github.com/pgRouting/pgrouting/pull/2522) bdAstar code
   simplification.
 
 **Documentation**
 
-* `2490 <https://github.com/pgRouting/pgrouting/pull/2490>` Automatic page
+* [#2490](https://github.com/pgRouting/pgrouting/pull/2490) Automatic page
   history links.
 
 pgRouting 3.5.1 Release Notes

diff --git a/doc/src/release_notes.rst b/doc/src/release_notes.rst
@@ -24,7 +24,7 @@ pgRouting 3.6.0 Release Notes
 
 .. rubric:: Official functions changes
 
-* `2516 <https://github.com/pgRouting/pgrouting/pull/2516>` Standarize output
+* `#2516 <https://github.com/pgRouting/pgrouting/pull/2516>`__ Standarize output
   pgr_aStar
 
   * Standarizing output columns to |short-generic-result|
@@ -33,7 +33,7 @@ pgRouting 3.6.0 Release Notes
     * ``pgr_aStar`` (`One to Many`) added ``end_vid`` column.
     * ``pgr_aStar`` (`Many to One`) added ``start_vid`` column.
 
-* `2523 <https://github.com/pgRouting/pgrouting/pull/2523>` Standarize output
+* `#2523 <https://github.com/pgRouting/pgrouting/pull/2523>`__ Standarize output
   pgr_bdAstar
 
   * Standarizing output columns to |short-generic-result|
@@ -42,27 +42,46 @@ pgRouting 3.6.0 Release Notes
     * ``pgr_bdAstar`` (`One to Many`) added ``end_vid`` column.
     * ``pgr_bdAstar`` (`Many to One`) added ``start_vid`` column.
 
+.. rubric:: Proposed functions changes
+
+* `#2544 <https://github.com/pgRouting/pgrouting/pull/2544>`__ Standarize output and modifying signature
+  pgr_withPointsDD
+
+  * New proposed signatures: ``driving side`` parameter changed from optional to compulsory
+
+    * ``pgr_withPointsDD`` (`Single vertex`)
+    * ``pgr_withPointsDD`` (`Multiple vertices`)
+
+  * Deprecated signatures:
+
+    * ``pgr_withpointsdd(text,text,bigint,double precision,boolean,character,boolean)``
+    * ``pgr_withpointsdd(text,text,anyarray,double precision,boolean,character,boolean,boolean)``
+
+  * Standarizing output columns to |result-bfs|
+
+    * ``pgr_withPointsDD`` (`Single vertex`) added ``depth`` and ``start_vid`` column.
+    * ``pgr_withPointsDD`` (`Multiple vertices`) added ``depth`` column.
 
 .. rubric:: C/C++ code enhancements
 
-* `2504 <https://github.com/pgRouting/pgrouting/pull/2504>` To C++ pg data get,
+* `#2504 <https://github.com/pgRouting/pgrouting/pull/2504>`__ To C++ pg data get,
   fetch and check.
 
   * Stopping support for compilation with MSVC.
 
-* `2505 <https://github.com/pgRouting/pgrouting/pull/2505>` Using namespace.
-* `2512 <https://github.com/pgRouting/pgrouting/pull/2512>` [Dijkstra] Removing
+* `#2505 <https://github.com/pgRouting/pgrouting/pull/2505>`__ Using namespace.
+* `#2512 <https://github.com/pgRouting/pgrouting/pull/2512>`__ [Dijkstra] Removing
   duplicate code on Dijkstra.
-* `2517 <https://github.com/pgRouting/pgrouting/pull/2517>` Astar code
+* `#2517 <https://github.com/pgRouting/pgrouting/pull/2517>`__ Astar code
   simplification.
-* `2521 <https://github.com/pgRouting/pgrouting/pull/2521>` Dijkstra code
+* `#2521 <https://github.com/pgRouting/pgrouting/pull/2521>`__ Dijkstra code
   simplification.
-* `2522 <https://github.com/pgRouting/pgrouting/pull/2522>` bdAstar code
+* `#2522 <https://github.com/pgRouting/pgrouting/pull/2522>`__ bdAstar code
   simplification.
 
 .. rubric:: Documentation
 
-* `2490 <https://github.com/pgRouting/pgrouting/pull/2490>` Automatic page
+* `#2490 <https://github.com/pgRouting/pgrouting/pull/2490>`__ Automatic page
   history links.
 
 pgRouting 3.5.1 Release Notes

diff --git a/doc/withPoints/pgr_withPointsDD.rst b/doc/withPoints/pgr_withPointsDD.rst
@@ -26,6 +26,24 @@
 
 .. rubric:: Availability
 
+* Version 3.6.0
+
+  * New proposed signatures:
+
+    * ``pgr_withPointsDD`` (`Single vertex`_)
+    * ``pgr_withPointsDD`` (`Multiple vertices`_)
+
+  * Deprecated signatures:
+
+    * ``pgr_withpointsdd(text,text,bigint,double precision,boolean,character,boolean)``
+    * ``pgr_withpointsdd(text,text,anyarray,double precision,boolean,character,boolean,boolean)``
+
+  * Standarizing output columns to |result-bfs|
+
+    * ``pgr_withPointsDD`` (`Single vertex`_) added ``depth`` and ``start_vid`` column.
+    * ``pgr_withPointsDD`` (`Multiple vertices`_) added ``depth`` column.
+
+
 * Version 2.2.0
 
   * New **proposed** function
@@ -45,12 +63,12 @@ Signatures
 .. admonition:: \ \
    :class: signatures
 
-   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vid**, **distance**, [**options A**])
-   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vids**, **distance**, [**options B**])
-   | **options A:** ``[directed, driving_side, details]``
-   | **options B:** ``[directed, driving_side, details, equicost]``
+   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vid**, **distance**, **driving side**, [**options A**])
+   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vids**, **distance**, **driving side**, [**options B**])
+   | **options A:** ``[directed, details]``
+   | **options B:** ``[directed, details, equicost]``
 
-   | RETURNS SET OF |result-generic-no-seq|
+   | RETURNS SET OF |result-bfs|
    | OR EMPTY SET
 
 .. index::
@@ -62,10 +80,10 @@ Single vertex
 .. admonition:: \ \
    :class: signatures
 
-   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vid**, **distance**, [**options**])
-   | **options:** ``[directed, driving_side, details]``
+   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vid**, **distance**, **driving side**, [**options**])
+   | **options:** ``[directed, details]``
 
-   | RETURNS SET OF |result-1-1-no-seq|
+   | RETURNS SET OF |result-bfs|
    | OR EMPTY SET
 
 :Example: Right side driving topology, from point :math:`1` within a distance of
@@ -84,10 +102,10 @@ Multiple vertices
 .. admonition:: \ \
    :class: signatures
 
-   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vids**, **distance**, [**options**])
-   | **options:** ``[directed, driving_side, details, equicost]``
+   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vids**, **distance**, **driving side**, [**options**])
+   | **options:** ``[directed, details, equicost]``
 
-   | RETURNS SET OF |result-m-1-no-seq|
+   | RETURNS SET OF |result-bfs|
    | OR EMPTY SET
 
 :Example: From point :math:`1` and vertex :math:`16` within a distance of
@@ -123,13 +141,28 @@ Parameters
      - ``ARRAY`` [**ANY-INTEGER**]
      - Array of identifiers of the root vertices.
 
-
        - Negative values represent a point
        - :math:`0` values are ignored
        - For optimization purposes, any duplicated value is ignored.
    * - **distance**
      - ``FLOAT``
      - Upper limit for the inclusion of a node in the result.
+   * - **driving side**
+     - ``CHAR``
+     - - Value in [``r``, ``R``, ``l``, ``L``, ``b``, ``B``] indicating if the driving side is:
+
+         - ``r``, ``R`` for right driving side,
+         - ``l``, ``L`` for left driving side.
+         - ``b``, ``B`` for both.
+
+       - Valid values differ for directed and undirected graphs:
+
+         - In directed graphs: [``r``, ``R``, ``l``, ``L``].
+         - In undirected graphs: [``b``, ``B``].
+
+Where:
+
+:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
 
 Optional parameters
 ...............................................................................
@@ -141,9 +174,21 @@ Optional parameters
 With points optional parameters
 ...............................................................................
 
-.. include:: withPoints-family.rst
-   :start-after: withPoints_optionals_start
-   :end-before: withPoints_optionals_end
+.. list-table::
+   :width: 81
+   :widths: 14 7 7 60
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``details``
+     - ``BOOLEAN``
+     - ``false``
+     - - When ``true`` the results will include the points that are in the path.
+       - When ``false`` the results will not include the points that are in the
+         path.
 
 Driving distance optional parameters
 ...............................................................................
@@ -172,43 +217,9 @@ Points SQL
 Result Columns
 -------------------------------------------------------------------------------
 
-RETURNS SET OF |result-generic-no-seq|
-
-.. list-table::
-   :width: 81
-   :widths: auto
-   :header-rows: 1
-
-   * - Parameter
-     - Type
-     - Description
-   * - ``seq``
-     - ``BIGINT``
-     - Sequential value starting from :math:`1`.
-   * - ``[start_vid]``
-     - ``BIGINT``
-     - Identifier of the root vertex.
-
-   * - ``node``
-     - ``BIGINT``
-     - Identifier of ``node`` within the limits from ``from_v``.
-   * - ``edge``
-     - ``BIGINT``
-     - Identifier of the ``edge`` used to arrive to ``node``.
-
-       - :math:`0` when ``node`` = ``from_v``.
-
-   * - ``cost``
-     - ``FLOAT``
-     - Cost to traverse ``edge``.
-   * - ``agg_cost``
-     - ``FLOAT``
-     - Aggregate cost from ``from_v`` to ``node``.
-
-Where:
-
-:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
-:ANY-NUMERIC: SMALLINT, INTEGER, BIGINT, REAL, FLOAT, NUMERIC
+.. include:: BFS-category.rst
+   :start-after: mst-bfs-dfs-dd-result-columns-start
+   :end-before: mst-bfs-dfs-dd-result-columns-end
 
 Additional Examples
 -------------------------------------------------------------------------------