From 83aceebe3356000c7e313f6732835426e7600808 Mon Sep 17 00:00:00 2001
From: Roland Conybeare <rconybeare@gmail.com>
Date: Wed, 8 May 2024 23:24:52 -0400
Subject: [PATCH] xo-unit: expand bu_store docs + uml diagram

---
 docs/CMakeLists.txt          |  2 +-
 docs/bu-store-class.rst      | 83 ++++++++++++++++++++++++++++++++++++
 docs/implementation.rst      |  2 +-
 docs/index.rst               |  1 +
 include/xo/unit/bu_store.hpp |  7 +++
 5 files changed, 93 insertions(+), 2 deletions(-)
 create mode 100644 docs/bu-store-class.rst

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 7e185091..2fe3b9af 100644
--- a/docs/CMakeLists.txt
+++ b/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
 )
diff --git a/docs/bu-store-class.rst b/docs/bu-store-class.rst
new file mode 100644
index 00000000..48614ebd
--- /dev/null
+++ b/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"));
diff --git a/docs/implementation.rst b/docs/implementation.rst
index da71bd15..e95d96d0 100644
--- a/docs/implementation.rst
+++ b/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.
 
diff --git a/docs/index.rst b/docs/index.rst
index e8b40b09..2b0a2153 100644
--- a/docs/index.rst
+++ b/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
 
diff --git a/include/xo/unit/bu_store.hpp b/include/xo/unit/bu_store.hpp
index 6906a4ed..11dd5d66 100644
--- a/include/xo/unit/bu_store.hpp
+++ b/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)
         {