API reference updates to reflect recent changes across the code-base [skip ci].

2 files changed, 110 insertions, 152 deletions

diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst
index 1253b1a2..89a9306e 100644
--- a/docs/source/development/reference/datatypes.rst
+++ b/docs/source/development/reference/datatypes.rst
@@ -62,7 +62,7 @@ Transformation objects
 
     Opaque object describing an area in which a transformation is performed.
 
-    .. note:: This object is not fully implemented yet. It is used with
+    .. note:: This object is not fully implemented yet. It is to be used with
               :c:func:`proj_create_crs_to_crs` to select the best transformation
               between the two input coordinate reference systems.
 
@@ -71,56 +71,56 @@ Transformation objects
 
 Various 2-dimensional coordinate data types.
 
-.. c:type:: LP
+.. c:type:: PJ_LP
 
     Geodetic coordinate, latitude and longitude. Usually in radians.
 
     .. code-block:: C
 
-        typedef struct { double lam, phi; } LP;
+        typedef struct { double lam, phi; } PJ_LP;
 
-    .. c:member:: double LP.lam
+    .. c:member:: double PJ_LP.lam
 
         Longitude. Lambda.
 
-    .. c:member:: double LP.phi
+    .. c:member:: double PJ_LP.phi
 
         Latitude. Phi.
 
 
-.. c:type:: XY
+.. c:type:: PJ_XY
 
     2-dimensional cartesian coordinate.
 
     .. code-block:: C
 
-        typedef struct { double x, y; } XY;
+        typedef struct { double x, y; } PJ_XY;
 
 
-    .. c:member:: double XY.lam
+    .. c:member:: double PJ_XY.lam
 
         Easting.
 
-    .. c:member:: double XY.phi
+    .. c:member:: double PJ_XY.phi
 
         Northing.
 
 
-.. c:type:: UV
+.. c:type:: PJ_UV
 
     2-dimensional generic coordinate. Usually used when contents can be either
-    a :c:type:`XY` or :c:type:`UV`.
+    a :c:type:`PJ_XY` or :c:type:`PJ_LP`.
 
     .. code-block:: C
 
-        typedef struct {double u, v; } UV;
+        typedef struct {double u, v; } PJ_UV;
 
 
-    .. c:member:: double UV.u
+    .. c:member:: double PJ_UV.u
 
         Longitude or easting, depending on use.
 
-    .. c:member:: double UV.v
+    .. c:member:: double PJ_UV.v
 
         Latitude or northing, depending on use.
 
@@ -131,66 +131,66 @@ Various 2-dimensional coordinate data types.
 The following data types are the 3-dimensional equivalents to the data
 types above.
 
-.. c:type:: LPZ
+.. c:type:: PJ_LPZ
 
-    3-dimensional version of :c:type:`LP`. Holds longitude, latitude and
+    3-dimensional version of :c:type:`PJ_LP`. Holds longitude, latitude and
     vertical component.
 
     .. code-block:: C
 
-        typedef struct { double lam, phi, z; } LPZ;
+        typedef struct { double lam, phi, z; } PJ_LPZ;
 
-    .. c:member:: double LPZ.lam
+    .. c:member:: double PJ_LPZ.lam
 
         Longitude. Lambda.
 
-    .. c:member:: double LPZ.phi
+    .. c:member:: double PJ_LPZ.phi
 
         Latitude. Phi.
 
-    .. c:member:: double LPZ.z
+    .. c:member:: double PJ_LPZ.z
 
         Vertical component.
 
 
-.. c:type:: XYZ
+.. c:type:: PJ_XYZ
 
-    Cartesian coordinate in 3 dimensions. Extension  of :c:type:`XY`.
+    Cartesian coordinate in 3 dimensions. Extension  of :c:type:`PJ_XY`.
 
     .. code-block:: C
 
-        typedef struct { double x, y, z; } XYZ;
+        typedef struct { double x, y, z; } PJ_XYZ;
 
-    .. c:member:: double XYZ.x
+    .. c:member:: double PJ_XYZ.x
 
         Easting.
 
-    .. c:member:: double XYZ.y
+    .. c:member:: double PJ_XYZ.y
 
         Northing.
 
-    .. c:member:: double XYZ.z
+    .. c:member:: double PJ_XYZ.z
 
         Vertical component.
 
 
-.. c:type:: UVW
+.. c:type:: PJ_UVW
 
-    3-dimensional extension of :c:type:`UV`.
+    3-dimensional extension of :c:type:`PJ_UV`.
 
     .. code-block:: C
 
-        typedef struct {double u, v, w; } UVW;
+        typedef struct {double u, v, w; } PJ_UVW;
 
-    .. c:member:: double UVW.u
+    .. c:member:: double PJ_UVW.u
 
         Longitude or easting, depending on use.
 
-    .. c:member:: double UVW.v
+    .. c:member:: double PJ_UVW.v
 
         Latitude or northing, depending on use.
 
-    .. c:member:: double UVW.w
+    .. c:member:: double PJ_UVW.w
 
         Vertical component.
 
@@ -204,7 +204,7 @@ domain.
 
 .. c:type:: PJ_LPZT
 
-    Spatiotemporal version of :c:type:`LPZ`.
+    Spatiotemporal version of :c:type:`PJ_LPZ`.
 
     .. code-block:: C
 
@@ -321,6 +321,7 @@ Complex coordinate types
 .. c:type:: PJ_COORD
 
     General purpose coordinate union type usefull in two, three and four dimensions.
+    This is the default coordinate datatype used in PROJ.
 
     .. code-block:: C
 
@@ -329,12 +330,12 @@ Complex coordinate types
             PJ_XYZT xyzt;
             PJ_UVWT uvwt;
             PJ_LPZT lpzt;
-            XYZ  xyz;
-            UVW  uvw;
-            LPZ  lpz;
-            XY   xy;
-            UV   uv;
-            LP   lp;
+            PJ_XYZ  xyz;
+            PJ_UVW  uvw;
+            PJ_LPZ  lpz;
+            PJ_XY   xy;
+            PJ_UV   uv;
+            PJ_LP   lp;
         } PJ_COORD ;
 
     .. c:member:: double v[4]
@@ -353,27 +354,27 @@ Complex coordinate types
 
         Longitude, latitude, vertical and time components.
 
-    .. c:member:: XYZ PJ_COORD.xyz
+    .. c:member:: PJ_XYZ PJ_COORD.xyz
 
         3-dimensional cartesian coordinate.
 
-    .. c:member:: UVW PJ_COORD.uvw
+    .. c:member:: PJ_UVW PJ_COORD.uvw
 
         3-dimensional generic coordinate.
 
-    .. c:member:: LPZ PJ_COORD.lpz
+    .. c:member:: PJ_LPZ PJ_COORD.lpz
 
         Longitude, latitude and vertical component.
 
-    .. c:member:: XY PJ_COORD.xy
+    .. c:member:: PJ_XY PJ_COORD.xy
 
         2-dimensional cartesian coordinate.
 
-    .. c:member:: UV PJ_COORD.uv
+    .. c:member:: PJ_UV PJ_COORD.uv
 
         2-dimensional generic coordinate.
 
-    .. c:member:: LP PJ_COORD.lp
+    .. c:member:: PJ_LP PJ_COORD.lp
 
         Longitude and latitude.
 
@@ -496,7 +497,7 @@ List structures
 
 .. c:type:: PJ_UNITS
 
-    Distance units defined in PROJ.4.
+    Distance units defined in PROJ.
 
     .. code-block:: C
 
@@ -525,7 +526,7 @@ List structures
 
 .. c:type:: PJ_PRIME_MERIDIANS
 
-    Prime meridians defined in PROJ.4.
+    Prime meridians defined in PROJ.
 
     .. code-block:: C
 
@@ -547,7 +548,7 @@ Info structures
 
 .. c:type:: PJ_INFO
 
-    Struct holding information about the current instance of PROJ.4. Struct is
+    Struct holding information about the current instance of PROJ. Struct is
     populated by :c:func:`proj_info`.
 
     .. code-block:: C
@@ -585,8 +586,9 @@ Info structures
 
     .. c:member:: char PJ_INFO.searchpath[512]
 
-        Search path for PROJ.4. List of directories separated by
-        semicolons,  e.g. "C:\Users\doctorwho;C:\OSGeo4W64\\share\proj".
+        Search path for PROJ. List of directories separated by
+        semicolons (Windows) or colons (non-Windows), e.g.
+        "C:\\Users\\doctorwho;C:\\OSGeo4W64\\share\\proj".
         Grids and init files are looked for in directories in the search path.
 
 .. c:type:: PJ_PROJ_INFO
@@ -630,7 +632,7 @@ Info structures
 .. c:type:: PJ_GRID_INFO
 
     Struct holding information about a specific grid in the search path of
-    PROJ.4. Populated with the function :c:func:`proj_grid_info`.
+    PROJ. Populated with the function :c:func:`proj_grid_info`.
 
     .. code-block:: C
 
@@ -684,7 +686,7 @@ Info structures
 .. c:type:: PJ_INIT_INFO
 
     Struct holding information about a specific init file in the search path of
-    PROJ.4. Populated with the function :c:func:`proj_init_info`.
+    PROJ. Populated with the function :c:func:`proj_init_info`.
 
     .. code-block:: C
 
diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst
index ea128954..8770f99b 100644
--- a/docs/source/development/reference/functions.rst
+++ b/docs/source/development/reference/functions.rst
@@ -205,83 +205,6 @@ Coordinate transformation
     :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number
 
 
-Initializers
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t)
-
-    Initializer for the :c:type:`PJ_COORD` union. The function is
-    shorthand for the otherwise convoluted assignment.
-    Equivalent to
-
-    .. code-block:: C
-
-        PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}};
-
-    or
-
-    .. code-block:: C
-
-        PJ_COORD c;
-        // Assign using the PJ_XYZT struct in the union
-        c.xyzt.x = 10.0;
-        c.xyzt.y = 20.0;
-        c.xyzt.z = 30.0;
-        c.xyzt.t = 40.0;
-
-    Since :c:type:`PJ_COORD` is a union of structs, the above assignment can
-    also be expressed in terms of the other types in the union, e.g.
-    :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`.
-
-
-    :param double x: 1st component in a :c:type:`PJ_COORD`
-    :param double y: 2nd component in a :c:type:`PJ_COORD`
-    :param double z: 3rd component in a :c:type:`PJ_COORD`
-    :param double t: 4th component in a :c:type:`PJ_COORD`
-    :returns: :c:type:`PJ_COORD`
-
-.. c:function:: PJ_OBS proj_obs(double x, double y, double z, double t,\
-                                double o, double p, double k,\
-                                int id, unsigned int flags)
-
-    Initializer for the :c:type:`PJ_OBS` union. The function is
-    shorthand for the otherwise convoluted assignment.
-    Equivalent to
-
-    .. code-block:: C
-
-        PJ_OBS c = {{{1.0, 2.0, 3.0, 4.0}}, {{5.0, 6.0, 7.0}}, 8, 9};
-
-    or
-
-    .. code-block:: C
-
-        PJ_OBS c;
-        // Assign using the PJ_COORD part of the struct in the union
-        o.coo.v[0] = 1.0;
-        o.coo.v[1] = 2.0;
-        o.coo.v[2] = 3.0;
-        o.coo.v[3] = 4.0;
-        o.anc.v[0] = 5.0;
-        o.anc.v[1] = 6.0;
-        o.anc.v[2] = 7.0;
-        o.id       = 8;
-        o.flags    = 9;
-
-    which is a bit too verbose in most practical applications.
-
-    :param double x: 1st component in a :c:type:`PJ_COORD`
-    :param double y: 2nd component in a :c:type:`PJ_COORD`
-    :param double z: 3rd component in a :c:type:`PJ_COORD`
-    :param double t: 4th component in a :c:type:`PJ_COORD`
-    :param double o: 1st component in a :c:type:`PJ_TRIPLET`
-    :param double p: 2nd component in a :c:type:`PJ_TRIPLET`
-    :param double k: 3rd component in a :c:type:`PJ_TRIPLET`
-    :param int id: Ancillary data, e.g. an ID
-    :param `flags`: Flags
-    :type `flags`: unsigned int
-    :returns: :c:type:`PJ_OBS`
-
 Error reporting
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -350,7 +273,7 @@ Info functions
 
 .. c:function:: PJ_INFO proj_info(void)
 
-    Get information about the current instance of the PROJ.4 library.
+    Get information about the current instance of the PROJ library.
 
     :returns: :c:type:`PJ_INFO`
 
@@ -366,7 +289,7 @@ Info functions
 
     Get information about a specific grid.
 
-    :param `gridname`: Gridname in the PROJ.4 searchpath
+    :param `gridname`: Gridname in the PROJ searchpath
     :type `gridname`: const char*
     :returns: :c:type:`PJ_GRID_INFO`
 
@@ -374,7 +297,7 @@ Info functions
 
     Get information about a specific init file.
 
-    :param `initname`: Init file in the PROJ.4 searchpath
+    :param `initname`: Init file in the PROJ searchpath
     :type `initname`: const char*
     :returns: :c:type:`PJ_INIT_INFO`
 
@@ -383,11 +306,11 @@ Lists
 
 .. c:function::  const PJ_OPERATIONS* proj_list_operations(void)
 
-    Get a pointer to an array of all operations in PROJ.4. The last entry
+    Get a pointer to an array of all operations in PROJ. The last entry
     of the returned array is a NULL-entry. The array is statically allocated
     and does not need to be freed after use.
 
-    Print a list of all operations in PROJ.4:
+    Print a list of all operations in PROJ:
 
     .. code-block:: C
 
@@ -400,7 +323,7 @@ Lists
 
 .. c:function:: const PJ_ELLPS* proj_list_ellps(void)
 
-    Get a pointer to an array of ellipsoids defined in PROJ.4. The last entry
+    Get a pointer to an array of ellipsoids defined in PROJ. The last entry
     of the returned array is a NULL-entry. The array is statically allocated
     and does not need to be freed after use.
 
@@ -408,7 +331,7 @@ Lists
 
 .. c:function:: const PJ_UNITS* proj_list_units(void)
 
-    Get a pointer to an array of distance units defined in PROJ.4. The last
+    Get a pointer to an array of distance units defined in PROJ. The last
     entry of the returned array is a NULL-entry. The array is statically
     allocated and does not need to be freed after use.
 
@@ -416,7 +339,7 @@ Lists
 
 .. c:function:: const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void)
 
-    Get a pointer to an array of prime meridians defined in PROJ.4. The last
+    Get a pointer to an array of prime meridians defined in PROJ. The last
     entry of the returned array is a NULL-entry. The array is statically
     allocated and does not need to be freed after use.
 
@@ -425,44 +348,77 @@ Lists
 Distances
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-.. c:function:: double proj_lp_dist(const PJ *P, LP a, LP b)
+.. c:function:: double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b)
 
     Calculate geodesic distance between two points in geodetic coordinates.
 
     :param PJ* P: Transformation object
-    :param LP a: Coordinate of first point
-    :param LP b: Coordinate of second point
+    :param PJ_COORD a: Coordinate of first point
+    :param PJ_COORD b: Coordinate of second point
     :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters.
 
-.. c:function:: double proj_lp_dist(const PJ *P, LPZ a, LPZ b)
+.. c:function:: double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b)
 
     Calculate geodesic distance between two points in geodetic coordinates.
 
     :param PJ* P: Transformation object
-    :param LPZ a: Coordinate of first point
-    :param LPZ b: Coordinate of second point
+    :param PJ_COORD a: Coordinate of first point
+    :param PJ_COORD b: Coordinate of second point
     :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters.
 
-.. c:function:: double proj_xy_dist(XY a, XY, b)
+.. c:function:: double proj_xy_dist(PJ_COORD a, PJ_COORD b)
 
     Calculate 2-dimensional euclidean between two projected coordinates.
 
-    :param XY a: First coordinate
-    :param XY b: Second coordinate
+    :param PJ_COORD a: First coordinate
+    :param PJ_COORD b: Second coordinate
     :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters.
 
-.. c:function:: double proj_xyz_dist(XYZ a, XYZ b)
+.. c:function:: double proj_xyz_dist(PJ_COORD a, PJ_COORD b)
 
     Calculate 3-dimensional euclidean between two projected coordinates.
 
-    :param XYZ a: First coordinate
-    :param XYZ b: Second coordinate
+    :param PJ_COORD a: First coordinate
+    :param PJ_COORD b: Second coordinate
     :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters.
 
 
 Various
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
+.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t)
+
+    Initializer for the :c:type:`PJ_COORD` union. The function is
+    shorthand for the otherwise convoluted assignment.
+    Equivalent to
+
+    .. code-block:: C
+
+        PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}};
+
+    or
+
+    .. code-block:: C
+
+        PJ_COORD c;
+        // Assign using the PJ_XYZT struct in the union
+        c.xyzt.x = 10.0;
+        c.xyzt.y = 20.0;
+        c.xyzt.z = 30.0;
+        c.xyzt.t = 40.0;
+
+    Since :c:type:`PJ_COORD` is a union of structs, the above assignment can
+    also be expressed in terms of the other types in the union, e.g.
+    :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`.
+
+
+    :param double x: 1st component in a :c:type:`PJ_COORD`
+    :param double y: 2nd component in a :c:type:`PJ_COORD`
+    :param double z: 3rd component in a :c:type:`PJ_COORD`
+    :param double t: 4th component in a :c:type:`PJ_COORD`
+    :returns: :c:type:`PJ_COORD`
+
+
 .. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coo)
 
     Measure internal consistency of a given transformation. The function
@@ -480,7 +436,7 @@ Various
     :returns: :c:type:`double` Distance between original coordinate and the \
               resulting coordinate after :c:data:`n` transformation iterations.
 
-.. c:function:: PJ_FACTORS proj_factors(PJ *P, LP lp)
+.. c:function:: PJ_FACTORS proj_factors(PJ *P, PJ_COORD lp)
 
     Calculate various cartographic properties, such as scale factors, angular
     distortion and meridian convergence. Depending on the underlying projection
@@ -492,7 +448,7 @@ Various
     :param `P`: Transformation object
     :type `P`: const PJ*
     :param `lp`: Geodetic coordinate
-    :type `lp`: const LP
+    :type `lp`: const PJ_COORD
     :returns: :c:type:`PJ_FACTORS`
 
 .. c:function:: double proj_torad(double angle_in_degrees)
@@ -531,7 +487,7 @@ Various
     :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`)
 
 
-.. c:function:: PJ_COORD proj_geoc_lat(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo)
+.. c:function:: PJ_COORD proj_geocentric_latitude(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo)
 
     Convert geographical to geocentric latitude.