xo-unit: docs: document xo::qty::dimension enum

docs/CMakeLists.txt

@@ -5,6 +5,6 @@ xo_docdir_doxygen_config()
 xo_docdir_sphinx_config(
     index.rst examples.rst glossary.rst install.rst implementation.rst
     quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst
-    unit-reference.rst unit-concept.rst unit-quantities.rst
+    unit-reference.rst unit-concept.rst unit-quantities.rst dimension-enum.rst
 )
 #xo_utest_coverage_config2()

docs/dimension-enum.rst

@@ -0,0 +1,16 @@
+.. _dimension:
+
+Dimension
+=========
+
+.. code-block:: cpp
+
+    #include <xo/unit/dimension.hpp>
+
+Identifies an abstract dimension, for example *mass* or *time*.
+
+.. doxygenenum:: xo::qty::dimension
+
+.. doxygenvariable:: xo::qty::n_dim
+
+.. doxygenfunction:: xo::qty::dim2str

docs/implementation.rst

@@ -21,7 +21,7 @@ Abstraction tower for *xo-unit* components.
     |       dimension       |
     +-----------------------+
 
-- quantity:    see :doc:`quantity-reference`.
+- quantity: see :doc:`quantity-reference`.
   quantity with compile-time unit work
 
 - xquantity:
@@ -49,7 +49,7 @@ Abstraction tower for *xo-unit* components.
 - basis_unit:
   a unit with a single dimension and scale.
 
-- dimension:
+- dimension: see :doc:`dimension-enum`.
   identifies a dimension, such as mass or time.
 
 Representation

docs/index.rst

@@ -36,6 +36,7 @@ runtime (since we can't construct new c++ types at runtime).
    unit-quantities
    quantity-reference
    unit-reference
+   dimension-enum
 
 Indices and Tables
 ------------------

include/xo/unit/dimension.hpp

@@ -6,7 +6,14 @@
 
 namespace xo {
     namespace qty {
+        /** @enum dimension
+         *  @brief represent an abstract dimension.
+         *
+         *  *xo-unit* units are expressed as a cartesian product
+         *  of powers of these dimensions.
+         **/
         enum class dimension {
+            /** sentinel value.  not a dimension **/
             invalid = -1,
 
             /** weight.  native unit = 1 gram **/
@@ -18,19 +25,24 @@ namespace xo {
             /** a currency amount. native unit depends on actual currency.
              *  For USD: one US dollar.
              *
-             *  NOTE: unit system isn't suitable for multicurrency work:
-             *        (1usd + 1eur) is well-defined,  but (1sec + 1m) is not.
+             *  NOTE: multicurrency work not supported by *xo-unit*.
+             *  - (1usd + 1eur) is well-defined.
+             *  - (1sec + 1m) is not.
              **/
             currency,
-            /** a screen price **/
+            /** A screen price.
+             *  The interpretation of prices is highly context dependent;
+             *  expect useful to bucket separately from currenty amounts.
+             **/
             price,
 
-            /** comes last, counts entries **/
+            /** not a dimension.  comes last, counts entries **/
             n_dim
         };
 
         using dim = dimension;
 
+        /** @brief string value for a dimension enum **/
         inline const char *
         dim2str(dimension x)
         {
@@ -45,6 +57,7 @@ namespace xo {
             return "?dim";
         }
 
+        /** @brief number of built-in dimensions, convenient for array sizing **/
         static constexpr std::size_t n_dim = static_cast<std::size_t>(dimension::n_dim);
     } /*namespace qty*/
 } /*namespace xo*/