Move content of proj_experimental.h to proj.h

[rouault]

Those functions have been used for ages by GDAL 3.X. They are not so much "experimental" nowadays.

No backward compatibility issue as proj_experimental.h includes proj.h

[mwtoews]

Should any of these be expanded into docs/source/development/reference/{datatypes,functions}.rst?

[rouault]

Should any of these be expanded into docs/source/development/reference/{datatypes,functions}.rst?

goot point. Adressed by additional commit

[mwtoews]

Suggest splitting advanced_cpp_binding into advanced_cpp_types and advanced_cpp_functions so they can be put into each of the datatypes.rst and functions.rst docs respectively. This name pair mirror the existing two groups: iso90111_types and iso90111_functions.

[rouault]

Suggest splitting advanced_cpp_binding into advanced_cpp_types and advanced_cpp_functions

done, by amending last commit

[mwtoews]

Thanks, rendered docs looks good! A few comments:

• Looking at the datatype docs, it is curious to see struct PJ_AXIS_DESCRIPTION and struct PJ_PARAM_DESCRIPTION do not show public members similar to struct PROJ_CELESTIAL_BODY_INFO. Is this because they needs to start with /** \brief ...?
• Potentially @since 9.4 could be added everywhere. But I wouldn't, since the docs are now versioned.
• Should there be section headers in the rst docs? Currently the former and advanced content are all under the "C API for ISO-19111 functionality" sections. The doxygengroup titles don't seem to show up. This is less relevant for the handful of new datatypes, but there are many new advanced functions that are added. Maybe insert a "Advanced C API" section for functions.rst?

[snowman2]

Potentially @since 9.4 could be added everywhere. But I wouldn't, since the docs are now versioned.

It is nice to have that so you don't have to dig through different versions of the docs to find out when it was added. But, not critical.

[rouault]

• Looking at the datatype docs, it is curious to see struct PJ_AXIS_DESCRIPTION and struct PJ_PARAM_DESCRIPTION do not show public members similar to struct PROJ_CELESTIAL_BODY_INFO. Is this because they needs to start with /** \brief ...?

I've tried different things, but don't manage to fix. Must be some Doxygen/Breathe/Sphinx bug

Potentially @SInCE 9.4 could be added everywhere. But I wouldn't, since the docs are now versioned.

I've added a global remark "Available in :file:proj.h since PROJ 9.4. Previously were available in :file:proj_experimental.h."

Should there be section headers in the rst docs?

Done, but it is too deep in the arborescence to show up in the left menu

[mwtoews]

Looks good, almost there. I just noticed a mix-up in the new docs from #3559 with these suggested corrections:

diff --git a/src/iso19111/c_api.cpp b/src/iso19111/c_api.cpp
index 17df96ee2..a353fe179 100644
--- a/src/iso19111/c_api.cpp
+++ b/src/iso19111/c_api.cpp
@@ -5208,7 +5208,7 @@ PJ *proj_create_conversion_two_point_equidistant(
  * linear_unit_conv_factor).
  * Angular parameters are expressed in (ang_unit_name, ang_unit_conv_factor).
  *
- * @deprecated. Replaced by proj_create_conversion_tunisia_mining_grid
+ * @since 9.2
  */
 PJ *proj_create_conversion_tunisia_mining_grid(
     PJ_CONTEXT *ctx, double center_lat, double center_long,
@@ -5242,7 +5242,7 @@ PJ *proj_create_conversion_tunisia_mining_grid(
  * linear_unit_conv_factor).
  * Angular parameters are expressed in (ang_unit_name, ang_unit_conv_factor).
  *
- * @since 9.2
+ * @deprecated Replaced by proj_create_conversion_tunisia_mining_grid
  */
 PJ *proj_create_conversion_tunisia_mapping_grid(
     PJ_CONTEXT *ctx, double center_lat, double center_long,

with the move from experimental header, should proj_create_conversion_tunisia_mapping_grid be dropped?

[rouault]

I just noticed a mix-up in the new docs from #3559 with these suggested corrections:

done

with the move from experimental header, should proj_create_conversion_tunisia_mapping_grid be dropped?

I would perhaps keep that for a PROJ 10