From 572b5bdf22770e0738e55b93788828297a444ee6 Mon Sep 17 00:00:00 2001
From: Mateusz Pusz <mateusz.pusz@gmail.com>
Date: Tue, 17 Mar 2020 18:06:45 +0100
Subject: [PATCH] Documentation for quantity constants added

---
 docs/CMakeLists.txt                       |  1 +
 docs/framework.rst                        |  1 +
 docs/framework/constants.rst              | 33 +++++++++++++++++++++++
 src/include/units/physical/si/constants.h |  8 ++----
 4 files changed, 37 insertions(+), 6 deletions(-)
 create mode 100644 docs/framework/constants.rst

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index a76a88ea..d00f7572 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -73,6 +73,7 @@ add_custom_command(OUTPUT "${SPHINX_INDEX_FILE}"
                        "${CMAKE_CURRENT_SOURCE_DIR}/faq.rst"
                        "${CMAKE_CURRENT_SOURCE_DIR}/framework.rst"
                        "${CMAKE_CURRENT_SOURCE_DIR}/framework/basic_concepts.rst"
+                       "${CMAKE_CURRENT_SOURCE_DIR}/framework/constants.rst"
                        "${CMAKE_CURRENT_SOURCE_DIR}/framework/conversions_and_casting.rst"
                        "${CMAKE_CURRENT_SOURCE_DIR}/framework/dimensions.rst"
                        "${CMAKE_CURRENT_SOURCE_DIR}/framework/quantities.rst"
diff --git a/docs/framework.rst b/docs/framework.rst
index 73de18e5..ec1502e2 100644
--- a/docs/framework.rst
+++ b/docs/framework.rst
@@ -14,5 +14,6 @@ Framework
     framework/quantities
     framework/dimensions
     framework/units
+    framework/constants
     framework/conversions_and_casting
     framework/text_output
diff --git a/docs/framework/constants.rst b/docs/framework/constants.rst
new file mode 100644
index 00000000..3fef5773
--- /dev/null
+++ b/docs/framework/constants.rst
@@ -0,0 +1,33 @@
+.. namespace:: units
+
+Quantity Constants
+==================
+
+In the **mp-units** library quantity constants are implemented as variable
+templates of `quantity` types parametrized by the quantity's representation
+type.
+
+Additionally, in case of the :term:`SI` its physical constants are put in
+separate namespaces named after the official release of the :term:`SI`
+specification. This is needed to be able to provide backward and forward
+compatibility as exact values of physical constants tend to change with time
+(in most cases they are getting more and more accurate with every
+specification release).
+
+For example the speed of light constant in :term:`SI` is defined as::
+
+    namespace si::si2019 {
+
+    template<Scalar Rep = double>
+    inline constexpr auto speed_of_light = velocity<metre_per_second, Rep>(299792458);
+
+    }
+
+The same constant defined for natural units may be provided as::
+
+    namespace natural {
+
+    template<Scalar Rep = double>
+    inline constexpr auto speed_of_light = velocity<unitless, Rep>(1);
+
+    }
diff --git a/src/include/units/physical/si/constants.h b/src/include/units/physical/si/constants.h
index ed19febd..454c49c2 100644
--- a/src/include/units/physical/si/constants.h
+++ b/src/include/units/physical/si/constants.h
@@ -30,9 +30,7 @@
 #include <units/physical/si/temperature.h>
 #include <units/physical/si/velocity.h>
 
-namespace units::si {
-
-namespace si2019 {
+namespace units::si::si2019 {
 
 template<Scalar Rep = double>
 inline constexpr auto planck_constant = energy<joule, Rep>(6.62607015e-34) * time<second, Rep>(1);
@@ -61,6 +59,4 @@ inline constexpr auto hyperfine_structure_transition_frequency = frequency<hertz
 template<Scalar Rep = double>
 inline constexpr auto standard_gravity = acceleration<metre_per_second_sq, Rep>(9.80665);
 
-}  // namespace si2019
-
-}  // namespace units::si
+}  // namespace units::si::si2019