From 28023d8a454f9163c203048624b2f1d4dd853fa5 Mon Sep 17 00:00:00 2001
From: Roland Conybeare <rconybeare@gmail.com>
Date: Tue, 7 May 2024 13:54:28 -0400
Subject: [PATCH] xo-unit: docs: document xo::qty::dimension enum

---
 docs/CMakeLists.txt           |  2 +-
 docs/dimension-enum.rst       | 16 ++++++++++++++++
 docs/implementation.rst       |  4 ++--
 docs/index.rst                |  1 +
 include/xo/unit/dimension.hpp | 21 +++++++++++++++++----
 5 files changed, 37 insertions(+), 7 deletions(-)
 create mode 100644 docs/dimension-enum.rst

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 28526b94..5577628e 100644
--- a/docs/CMakeLists.txt
+++ b/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()
diff --git a/docs/dimension-enum.rst b/docs/dimension-enum.rst
new file mode 100644
index 00000000..dd7b1edc
--- /dev/null
+++ b/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
diff --git a/docs/implementation.rst b/docs/implementation.rst
index a48fe480..3553d2ce 100644
--- a/docs/implementation.rst
+++ b/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
diff --git a/docs/index.rst b/docs/index.rst
index f6fa3413..e912c898 100644
--- a/docs/index.rst
+++ b/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
 ------------------
diff --git a/include/xo/unit/dimension.hpp b/include/xo/unit/dimension.hpp
index 0f056678..c28936e2 100644
--- a/include/xo/unit/dimension.hpp
+++ b/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*/