xo-unit: expand bu_store docs + uml diagram

docs/CMakeLists.txt

@@ -5,7 +5,7 @@ xo_docdir_doxygen_config()
 xo_docdir_sphinx_config(
     index.rst examples.rst glossary.rst install.rst implementation.rst development.rst
     quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst
-    unit-reference.rst unit-concept.rst unit-quantities.rst basis-unit-reference.rst
+    unit-reference.rst unit-concept.rst unit-quantities.rst bu-store-class.rst basis-unit-reference.rst
     basis-unit-class.rst basis-unit-constants.rst
     dimension-enum.rst
 )

docs/bu-store-class.rst

@@ -0,0 +1,83 @@
+.. _bu-store-class:
+
+Basis Unit Store
+================
+
+.. code-block:: cpp
+
+    #include <xo/unit/bu_store.hpp>
+
+    namespace bu = xo::qty::bu;
+
+A :code:`xo::qty::bu_store` is a small, constexpr, key-value store associating
+abbreviations with basis units. To satisfy the constexpr requirement,
+all unit abbreviations are irrevocably established from ``bu_store``'s constructor.
+
+The constant ``bu_abbrev_store`` contains a single instance of ``bu_store``,
+recording all built-in units along with their associated abbreviations
+
+.. uml::
+    :caption: basis-unit store
+    :scale: 99%
+    :align: center
+
+    map mass_table {
+    bu::milligram => "mg"
+    bu::gram => "g"
+    bu::kilogram => "kg"
+    }
+
+    map distance_table {
+    bu::millimeter => "mm"
+    bu::meter => "m"
+    bu::kilometer => "km"
+    }
+
+    map time_table {
+    bu::millisecond => "ms"
+    bu::second => "s"
+    bu::minute => "min"
+    bu::hour => "hr"
+    }
+
+    object bu_abbrev_store<<bu_store>>
+    bu_abbrev_store : bu_abbrev_vv[dim::mass] = mass_table
+    bu_abbrev_store : bu_abbrev_vv[dim::distance] = distance_table
+    bu_abbrev_store : bu_abbrev_vv[dim::time] = time_table
+
+    bu_abbrev_store o-- mass_table
+    bu_abbrev_store o-- distance_table
+    bu_abbrev_store o-- time_table
+
+
+This class supports the implementation of ``natural_unit::abbrev()``.
+
+Application code is not expected to interact directly with it.
+
+.. doxygenclass:: xo::qty::bu_store
+
+Constants
+---------
+
+Provides dictionary of unit abbreviations
+
+Application code is not expected to interact directly with ``bu_abbrev_store``.
+
+.. doxygenvariable:: xo::qty::bu_abbrev_store
+
+Functions
+---------
+
+.. doxygenfunction:: xo::qty::bu_abbrev
+
+For example:
+
+.. code-block:: cpp
+
+    #include <xo/unit/bu_store.hpp>
+
+    namespace bu = xo::qty::bu;
+    using xo::qty::bu_abbrev;
+    using xo::flatstring;
+
+    static_assert(bu_abbrev(bu::kilogram) == xo::flatstring("kg"));

docs/implementation.rst

@@ -52,7 +52,7 @@ Abstraction tower for *xo-unit* components.
 
   A power of a basis unit. Has a single dimension.
 
-- bu_store:
+- bu_store: see :doc:`bu-store-class`.
 
   Associates basis units with abbreviations.
 

docs/index.rst

@@ -37,6 +37,7 @@ runtime (since we can't construct new c++ types at runtime).
    unit-quantities
    quantity-reference
    unit-reference
+   bu-store-class
    basis-unit-reference
    dimension-enum
 

include/xo/unit/bu_store.hpp

@@ -210,8 +210,15 @@ namespace xo {
             std::array<bu_dim_store, n_dim> bu_abbrev_vv_;
         };
 
+        /** @brief global abbreviation store.
+         *
+         *  @note
+         *  Extending the contents of this store at runtime is not supported,
+         *  in favor of preserving constexpr abbreviations.
+         **/
         static constexpr bu_store bu_abbrev_store = bu_store();
 
+        /** @brief get abbreviation for basis-unit @p bu **/
         constexpr bu_abbrev_type
         bu_abbrev(const basis_unit & bu)
         {