update binning plugin domain info docs

docs/source/usage/plugins/binningPlugin.rst

@@ -101,22 +101,6 @@ For two fields with one extra data parameter:
 
   Fields and extra data may be tuples with multiple elements which are unpacked and passed to the user-defined functors. Therefore, it is the responsibility of the user to ensure that their functors have an appropriate number of arguments to match the provided tuples.
 
-Domain Info
-"""""""""""
-Enables the user to find the location of the particle or field in the simulation domain. Contains
-
-For particle binning, the ``DomainInfo`` class contains:
-
-.. doxygenclass:: picongpu::plugins::binning::DomainInfoBase
-  :members:
-
-The global and local offsets can be understood by looking at the `PIConGPU domain definitions <https://github.com/ComputationalRadiationPhysics/picongpu/wiki/PIConGPU-domain-definitions>`_.
-
-For particle binning, the particle position is obtained at cell precision by default. To get sub-cell precision or SI units, use optional template parameters with ``getParticlePosition<DomainOrigin, PositionPrecision, PositionUnits>``.
-
-For field binning, the field ``DomainInfo`` additionally holds the localCellIndex in the supercell and has a method to ``getCellIndex<DomainOrigin, PositionUnits>`` to get the current cell index being binned relative to an origin (global, total, local). To get the exact position of the fields inside the cell, relative to the cell index, use the ``FieldPosition`` trait.
-
-
 Dimensionality and units
 ^^^^^^^^^^^^^^^^^^^^^^^^
 Users can specify the units of their functor output using a 7 dimensional array. Each element of the array corresponds to an SI base unit, and the value stored in that index is the exponent of the unit.
@@ -132,6 +116,75 @@ If no units are given, the quantity is assumed to be dimensionless.
 .. doxygenenum:: picongpu::SIBaseUnits::SIBaseUnits_t
 
 
+Domain Info
+-----------
+The binning plugin passes the domain info object to functors as a parameter to give the user access to some useful PIConGPU quantities inside the functor. 
+Importantly, it enables the user to find the location of the particle or field in the simulation domain.
+
+The ``DomainInfo`` class contains:
+
+.. doxygenclass:: picongpu::plugins::binning::DomainInfoBase
+  :members:
+
+The global and local offsets can be understood by looking at the `PIConGPU domain definitions <https://github.com/ComputationalRadiationPhysics/picongpu/wiki/PIConGPU-domain-definitions>`_.
+
+Particle binning
+^^^^^^^^^^^^^^^^
+
+For particle binning, we can use the ``getParticlePosition`` function. 
+
+.. code-block:: cpp
+
+    getParticlePosition<DomainOrigin, PositionPrecision, PositionUnits>()
+
+The particle position has the default precision set to cell precision, and the position is returned in cell units by default.
+
+To request a different origin, precision, or unit system, use the template parameters as described below.
+
+Field binning
+^^^^^^^^^^^^^
+
+For field binning, ``DomainInfo`` additionally stores the ``localCellIndex`` within the supercell we can use the ``getCellIndex`` function.
+
+.. code-block:: cpp
+
+    getCellIndex<DomainOrigin, PositionUnits>()
+
+This returns the current cell index being binned relative to the selected origin.
+
+To obtain the exact position of a field inside the cell, relative to the cell index, use the ``FieldPosition`` trait.
+
+Domain origin
+^^^^^^^^^^^^^
+
+The reference origin for returned positions is selected with ``DomainOrigin``:
+
+The available origins are:
+
+.. doxygenenum:: picongpu::plugins::binning::DomainOrigin
+
+Position precision
+^^^^^^^^^^^^^^^^^^
+
+For particle positions, the precision is selected with ``PositionPrecision``.
+
+The available precisions are:
+
+.. doxygenenum:: picongpu::plugins::binning::PositionPrecision
+
+Position units
+^^^^^^^^^^^^^^
+
+The output units for positions are selected with ``PositionUnits``.
+
+The available units are:
+
+.. doxygenenum:: picongpu::plugins::binning::PositionUnits
+
+.. note::
+
+    Using positions in SI/PIC units introduces floating point numerical errors and may be especially problematic when using the ``TOTAL`` origin with moving window, because floating-point precision decreases as the distance from the origin increases.
+
 Axis
 ----
 Axis is a combination of a :ref:`functor description <usage/plugins/binningPlugin:Functor Description>` and an  :ref:`axis splitting <usage/plugins/binningPlugin:Axis Splitting>`.

include/picongpu/plugins/binning/DomainInfo.hpp

@@ -90,27 +90,30 @@ namespace picongpu
 
         enum class DomainOrigin
         {
-            // absolute origin of the simulation, inlcudes areas that are not in the current global volume,
-            // i.e. areas that have gone out due to the sliding window
+            /** Absolute origin of the simulation. This includes regions that are no longer part of the current global
+             * volume because they have moved out of the sliding window. */
             TOTAL,
-            // origin of the current sliding window, i.e. the currently simulated volume over all GPUs, no guards
+            /** Origin of the current sliding window, i.e. the currently simulated domain across all GPUs, excluding
+             * guard cells. */
             GLOBAL,
-            // origin of the current ("my") GPU, no guards
+            /** Origin of the local domain on the current GPU, excluding guard cells. */
             LOCAL,
-            /** origin relative to the origin of the sliding window. This origin only starts moving with the sliding
+            /** Origin relative to the origin of the sliding window. This origin only starts moving with the sliding
              *  window and is not discretized to the cell grid
              */
             MOVING_WINDOW,
-            // origin of the current ("my") GPU, including guards
+            /** Origin of the local domain on the current GPU, including guard cells. This setting is in particular
+             * used to access field data for the current cell with getCellIndex. */
             LOCAL_WITH_GUARDS
         };
 
         enum class PositionPrecision
         {
-            // Returns the cell index of the particle
+            /** Returns the particle position at cell precision, i.e. as a cell index. */
             CELL,
-            // Returns the position of the particle as the cell index + the position of the particle inside the cell
-            // [0,1) This value is a floating point number of cells
+            /** Returns the particle position with sub-cell precision, i.e. as the cell index plus the particle
+             * position inside the cell in the range [0,1). The result is therefore a floating-point position in units
+             * of cells. */
             SUB_CELL
         };
 

include/picongpu/traits/SIBaseUnits.hpp

@@ -33,13 +33,20 @@ namespace picongpu
     {
         enum SIBaseUnits_t
         {
-            length = 0, // L
-            mass = 1, // M
-            time = 2, // T
-            electricCurrent = 3, // I
-            thermodynamicTemperature = 4, // theta
-            amountOfSubstance = 5, // N
-            luminousIntensity = 6, // J
+            /** L */
+            length = 0,
+            /** M */
+            mass = 1,
+            /** T */
+            time = 2,
+            /** I */
+            electricCurrent = 3,
+            /** theta */
+            thermodynamicTemperature = 4,
+            /** N */
+            amountOfSubstance = 5,
+            /** J */
+            luminousIntensity = 6,
         };
     } // namespace SIBaseUnits