Doc: update docs of proj_create(), proj_create_argv() and proj_create_crs_to_crs() (refs #1223)

1 files changed, 39 insertions, 14 deletions

diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst
index ef84d489..aa548664 100644
--- a/docs/source/development/reference/functions.rst
+++ b/docs/source/development/reference/functions.rst
@@ -29,7 +29,9 @@ paragraph for more details.
 
 .. c:function:: PJ* proj_create(PJ_CONTEXT *ctx, const char *definition)
 
-    Create a transformation object from a proj-string.
+    Create a transformation object, or a CRS object, from a proj-string,
+    a WKT string, or object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326",
+    "urn:ogc:def:coordinateOperation:EPSG::1671").
 
     Example call:
 
@@ -37,6 +39,16 @@ paragraph for more details.
 
         PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel");
 
+    If a proj-string contains a +type=crs option, then it is interpreted as
+    a CRS definition. In particular geographic CRS are assumed to have axis
+    in the longitude, latitude order and with degree angular unit. The use
+    of proj-string to describe a CRS is discouraged. It is a legacy means of
+    conveying CRS descriptions: use of object codes (EPSG:XXXX typically) or
+    WKT description is recommended for better expressivity.
+
+    If a proj-string does not contain +type=crs, then it is interpreted as a
+    coordination operation / transformation.
+
     If creation of the transformation object fails, the function returns `0` and
     the PROJ error number is updated. The error number can be read with
     :c:func:`proj_errno` or :c:func:`proj_context_errno`.
@@ -50,7 +62,7 @@ paragraph for more details.
 
 .. c:function:: PJ* proj_create_argv(PJ_CONTEXT *ctx, int argc, char **argv)
 
-    Create transformation object with argc/argv-style initialization. For this
+    Create a transformation object, or a CRS object, with argc/argv-style initialization. For this
     application each parameter in the defining proj-string is an entry in :c:data:`argv`.
 
     Example call:
@@ -60,6 +72,13 @@ paragraph for more details.
         char *args[3] = {"proj=utm", "zone=32", "ellps=GRS80"};
         PJ* P = proj_create_argv(0, 3, args);
 
+    If there is a type=crs argument, then the arguments are interpreted as
+    a CRS definition. In particular geographic CRS are assumed to have axis
+    in the longitude, latitude order and with degree angular unit.
+
+    If there is no type=crs argument, then it is interpreted as a
+    coordination operation / transformation.
+
     If creation of the transformation object fails, the function returns `0` and
     the PROJ error number is updated. The error number can be read with
     :c:func:`proj_errno` or :c:func:`proj_context_errno`.
@@ -71,28 +90,34 @@ paragraph for more details.
     :param char** argv: Vector of strings with proj-string parameters, e.g. ``+proj=merc``
     :returns: :c:type:`PJ*`
 
-.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *srid_from, const char *srid_to, PJ_AREA *area)
+.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *source_crs, const char *target_crs, PJ_AREA *area)
 
     Create a transformation object that is a pipeline between two known
     coordinate reference systems.
 
-    :c:data:`srid_from` and :c:data:`srid_to` should be the value part of a ``+init=...`` parameter
-    set, i.e. "epsg:25833" or "IGNF:AMST63". Any projection definition that
-    can be found in a init-file in :envvar:`PROJ_LIB` is a valid input to this function.
+    source_crs and target_crs can be :
+
+        - a "AUTHORITY:CODE", like EPSG:25832. When using that syntax for a source
+          CRS, the created pipeline will expect that the values passed to :c:func:`proj_trans`
+          respect the axis order and axis unit of the official definition (
+          so for example, for EPSG:4326, with latitude first and longitude next,
+          in degrees). Similarly, when using that syntax for a target CRS, output
+          values will be emitted according to the official definition of this CRS.
+
+        - a PROJ string, like "+proj=longlat +datum=WGS84".
+          When using that syntax, the axis order and unit for geographic CRS will
+          be longitude, latitude, and the unit degrees.
+
+        - more generally any string accepted by :c:func:`proj_create`
 
-    For now the function mimics the cs2cs app: An input and an output CRS is
-    given and coordinates are transformed via a hub datum (WGS84). This
-    transformation strategy is referred to as "early-binding" by the EPSG. The
-    function can be extended to support "late-binding" transformations in the
-    future without affecting users of the function. When the function is extended
-    to the late-binding approach the :c:data:`area` argument will be used. For
-    now it is just a place-holder for a future improved implementation.
+    An "area of use" can be specified in area. When it is supplied, the more
+    accurate transformation between two given systems can be chosen.
 
     Example call:
 
     .. code-block:: C
 
-        PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833", 0);
+        PJ *P = proj_create_crs_to_crs(0, "EPSG:25832", "EPSG:25833", 0);
 
     If creation of the transformation object fails, the function returns `0` and
     the PROJ error number is updated. The error number can be read with