Python documentation, C++ documentation fixes

include/openPMD/Mesh.hpp

@@ -197,7 +197,7 @@ class Mesh : public BaseRecord<MeshRecordComponent>
 
     /** Alias for `setGridUnitSIPerDimension(std::vector<double>)`.
      *
-     * Set the unit-conversion factor per dimension to multiply each value in
+     * Set the unit-conversion factors per axis to multiply each value in
      * Mesh::gridSpacing and Mesh::gridGlobalOffset, in order to convert from
      * simulation units to SI units.
      *
@@ -214,14 +214,14 @@ class Mesh : public BaseRecord<MeshRecordComponent>
     Mesh &setGridUnitSI(std::vector<double> gridUnitSI);
 
     /**
-     * @return  A vector of the gridUnitSI per grid dimension as defined
-     * by the axisLabels. If the gridUnitSI is defined as a scalar
+     * @return  A vector of the gridUnitSI per grid axis in the order of
+     * the axisLabels. If the gridUnitSI is defined as a scalar
      * (legacy openPMD), the dimensionality is determined and a vector of
      * `dimensionality` times the scalar vector is returned.
      */
     std::vector<double> gridUnitSIPerDimension() const;
 
-    /* Set the unit-conversion factor per dimension to multiply each value in
+    /* Set the unit-conversion factors per axis to multiply each value in
      * Mesh::gridSpacing and Mesh::gridGlobalOffset, in order to convert from
      * simulation units to SI units.
      *

include/openPMD/binding/python/UnitDimension.hpp

@@ -24,7 +24,7 @@ namespace openPMD
 {
 namespace python
 {
-    constexpr auto doc_unit_dimension = R"docstr(
+    constexpr auto doc_unit_dimension = &R"docstr(
 Return the physical dimension (quantity) of a record
 
 Annotating the physical dimension of a record allows us to read data
@@ -40,7 +40,29 @@ See https://en.wikipedia.org/wiki/International_System_of_Quantities#Base_quanti
 See https://github.com/openPMD/openPMD-standard/blob/1.1.0/STANDARD.md#required-for-each-record
 
 Returns the powers of the 7 base measures in the order specified above.
-)docstr";
+)docstr"[1];
+
+    constexpr auto doc_mesh_unit_dimension = &R"docstr(
+Return the physical dimension (quantity) of the record axes
+
+Annotating the physical dimension of the record axes allows us to read data
+sets with arbitrary names and understand their purpose simply by
+dimensional analysis. The dimensional base quantities in openPMD are
+in order: length (L), mass (M), time (T), electric current (I),
+thermodynamic temperature (theta), amount of substance (N),
+luminous intensity (J) after the international system of quantities
+(ISQ).
+This attribute may be left out, the axes will then be interpreted as spatial.
+
+See https://en.wikipedia.org/wiki/Dimensional_analysis
+See https://en.wikipedia.org/wiki/International_System_of_Quantities#Base_quantities
+See https://github.com/openPMD/openPMD-standard/blob/1.1.0/STANDARD.md#required-for-each-record
+
+Returns the powers of the 7 base measures in the order specified above, listed
+for each axis in the order of the axisLabels.
+This attribute has been introduced as part of openPMD 2.0.0 in:
+Ref.: https://github.com/openPMD/openPMD-standard/pull/193
+)docstr"[1];
 
 } // namespace python
 } // namespace openPMD

src/binding/python/Mesh.cpp

@@ -67,7 +67,8 @@ void init_Mesh(py::module &m)
         .def_property(
             "grid_unit_dimension",
             &Mesh::gridUnitDimension,
-            &Mesh::setGridUnitDimension)
+            &Mesh::setGridUnitDimension,
+            python::doc_mesh_unit_dimension)
 
         .def_property(
             "geometry",
@@ -105,6 +106,13 @@ void init_Mesh(py::module &m)
             &Mesh::setGridGlobalOffset)
         .def_property(
             "grid_unit_SI",
+            /*
+             * Using pybind11's support for std::variant in order to implement a
+             * polymorphic type for this property. Will be a scalar double in
+             * openPMD 1.*, a list of double in openPMD 2.*.
+             * Unlike in the C++ API, this means that no new API calls
+             * such as gridUnitSIPerDimension() must be added.
+             */
             [](Mesh &self) {
                 using return_t = std::variant<double, std::vector<double>>;
                 if (self.openPMDStandard() < OpenpmdStandard::v_2_0_0)
@@ -123,7 +131,28 @@ void init_Mesh(py::module &m)
                             static_cast<decltype(arg_resolved)>(arg_resolved));
                     },
                     arg);
-            })
+            },
+            &R"(
+For openPMD versions 1.*:
+
+Set the unit-conversion factor to multiply each value in
+Mesh.grid_spacing and Mesh.grid_global_offset, in order to convert from
+simulation units to SI units.
+The type is a scalar floating point.
+
+For openPMD versions 2.*:
+
+Set the unit-conversion **factors per axis** in the order of the axisLabels
+to multiply each value in Mesh.grid_spacing and Mesh.grid_global_offset,
+in order to convert from simulation units to SI units.
+The type is a list of floating points.
+
+When writing a scalar value to an openPMD 2.* file, a warning will be printed
+(for enabling a more comfortable migration to openPMD 2.*).
+When writing a list value to an openPMD 1.* file, an error will be thrown,
+since most openPMD 1.*-based readers will not be able to interpret this
+properly.
+Ref.: https://github.com/openPMD/openPMD-standard/pull/193)"[1])
         .def_property(
             "time_offset",
             &Mesh::timeOffset<double>,