docs: Documentation updated

docs/conf.py

@@ -294,6 +294,10 @@ nitpicky = True
 # or ('envvar', 'LD_LIBRARY_PATH').
 nitpick_ignore = []
 
+# True to prefix each section label with the name of the document it is in,
+# followed by a colon. Useful for avoiding ambiguity when the same section
+# heading appears in different documents.
+autosectionlabel_prefix_document = True
 
 # -- C++ configuration ---------------------------------------------------
 

docs/design/directories.rst

@@ -57,7 +57,7 @@ Library Directories Structure
 .. seealso::
 
   More information on provided :term:`systems of units <system of units>` can be
-  found in :ref:`Systems` chapter.
+  found in :ref:`reference/systems:Systems` chapter.
 
 .. important::
 

docs/faq.rst

@@ -39,7 +39,8 @@ of units of the same physical dimension between different systems.
 
 .. seealso::
 
-    More details on this subject can be found in the :ref:`Custom Systems` chapter.
+    More details on this subject can be found in the
+    :ref:`use_cases/extensions:Custom Systems` chapter.
 
 
 Why a dimensionless quantity is not just an fundamental arithmetic type?
@@ -66,8 +67,8 @@ This is why it was decided to go with the current approach.
 
 .. seealso::
 
-    More information on the current design can be found in :ref:`Dimensionless quantities`
+    More information on the current design can be found in
-    chapter.
+    the :ref:`framework/quantities:Dimensionless Quantities` chapter.
 
 
 Why do we spell ``metre`` instead of ``meter``?
@@ -114,7 +115,7 @@ to obey the rules and be consistent with ISO specifications.
 .. seealso::
 
     We do understand engineering reality and constraints and that is why the library
-    has the option of :ref:`ASCII-only quantity symbols`.
+    has the option of :ref:`framework/text_output:ASCII-only quantity symbols`.
 
 
 Compilation Errors
@@ -124,6 +125,7 @@ error: reference to ‘time’ is ambiguous
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Unfortunately, if `using-directives <https://en.cppreference.com/w/cpp/language/namespace#Using-directives>`_
-(i.e. ``using namespace units::physical::si``) are being used, `units::physical::si::time` will
+(i.e. ``using namespace units::physical::si``) are being used, `units::physical::si::time`
-collide with C `time <https://en.cppreference.com/w/c/chrono/time>`_ function. In such a case the library's
+will collide with C `time <https://en.cppreference.com/w/c/chrono/time>`_ function. In
-``time`` function needs to be prefixed with at least one (or all) namespace names.
+such a case the library's ``time`` function needs to be prefixed with at least one (or all)
+namespace names.

docs/framework/basic_concepts.rst

@@ -45,7 +45,7 @@ The most important concepts in the library are `Unit`, `Dimension`,
 
     [<abstract>PointKind]<-[QuantityPointKind]
     [Kind]<-[PointKind]
-    [QuantityKind]-<[QuantityPointKind]
+    [QuantityKind]<-[QuantityPointKind]
 
 `Unit` is a basic building block of the library. Every dimension works with
 a concrete hierarchy of units. Such hierarchy defines a reference unit and

docs/framework/conversions_and_casting.rst

@@ -55,8 +55,7 @@ Implicit conversions are allowed only across quantities of the same dimension:
 Explicit
 --------
 
-Explicit conversions are available with
+Explicit conversions are available with the `quantity_cast`, `quantity_point_cast`,
-the `quantity_cast`, `quantity_point_cast`,
 `quantity_kind_cast`, and `quantity_point_kind_cast` function templates.
 They are especially useful to force a truncating conversion across quantities of the same
 dimension for integral representation types and ratios that may cause precision loss::
@@ -66,9 +65,9 @@ dimension for integral representation types and ratios that may cause precision
 
 .. seealso::
 
-    Explicit casts are also really useful when working with legacy interfaces. More
+    Explicit casts are also really useful when working with legacy interfaces.
-    information on this subject can be found in :ref:`Working with Legacy Interfaces`
+    More information on this subject can be found in the
-    chapter.
+    :ref:`use_cases/legacy_interfaces:Working with Legacy Interfaces` chapter.
 
 Quantity Cast Overloads
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -109,17 +108,18 @@ accept a `PointKind` and `Kind` instead of a `Dimension`, respectively.
 
 .. seealso::
 
-    For more information on conversion and casting and on how to extend the above "integral"
+    For more information on conversion and casting and on how to extend the above
-    vs "floating-point" logic please refer to the :ref:`Using Custom Representation Types`
+    "integral" vs "floating-point" logic please refer to the
-    chapter.
+    :ref:`use_cases/custom_representation_types:Using Custom Representation Types` chapter.
 
 
 Implicit conversions of dimensionless quantities
 ------------------------------------------------
 
-As noted in the :ref:`Dimensionless Quantities` chapter, :term:`quantity of dimension one`
+As noted in the :ref:`framework/quantities:Dimensionless Quantities` chapter,
-is somehow special but still obey most of the rules defined for quantities. However, as they
+:term:`quantity of dimension one` is somehow special but still obey most of the rules defined
-represent numbers it would be highly uncomfortable to every time type::
+for quantities. However, as they represent numbers it would be highly uncomfortable to every
+time type::
 
     const auto d1 = 10_q_km;
     const auto d2 = 3_q_km;

docs/framework/dimensions.rst

@@ -8,8 +8,11 @@ In the previous chapter we briefly introduced the notion of a physical
 Length, time, speed, area, energy are only a few examples of physical
 dimensions.
 
-Operations
+Arithmetics
-----------
+-----------
+
+Quantities
+++++++++++
 
 Quantities of the same dimension can be easily added or subtracted with
 each other and the result will always be a quantity of the same dimension:
@@ -61,24 +64,32 @@ dimension, than we will end up with just a dimensionless quantity:
     Dimensionless auto v1 = dur1 / dur2;    // quantity(5)
     Dimensionless auto v2 = dur1 * fr1;     // quantity(50)
 
-Quantity kinds behave the same as quantities for addition, substraction, and
+Quantity Kinds
-multiplication with, and division by a :term:`scalable number`.
+++++++++++++++
 
-Multiplication and divison with a quantity
+Quantity kinds behave the same as quantities for addition and subtraction.
-(but not a quantity kind) is allowed.
+The same behavior is also provided for multiplication with, and division by
-The result is a quantity kind with the appropiate dimension
+a :term:`scalable number`.
-and related to the original quantity kind.
+
+Multiplication and division with a quantity (but not a quantity kind) is allowed.
+The result is a quantity kind with the appropriate dimension
+and related to the original quantity kind:
+
+.. code-block::
+    :emphasize-lines: 5-6
 
     struct height : kind<height, dim_length> {};
     struct rate_of_climb : derived_kind<rate_of_climb, height, dim_speed> {};
 
     quantity_kind h(height{}, 100 * m);
     quantity_point_kind rate = h / (25 * s);
-      // `quantity_point_kind<rate_of_climb, si::metre_per_second, int>(4 * m / s)`
+      // quantity_point_kind<rate_of_climb, si::metre_per_second, int>(4 * m / s)
+
+Quantity Points
++++++++++++++++
 
 Quantity points have a more restricted set of operations.
-Quantity points can't be added together,
+Quantity can be added to or subtracted from a quantity point.
-but can be added to or subtracted from quantities.
 The result will always be a quantity point of the same dimension:
 
 .. code-block::
@@ -90,17 +101,6 @@ The result will always be a quantity point of the same dimension:
     QuantityPoint auto res2 = dist1 + quantity_point{dist2};
     QuantityPoint auto res3 = quantity_point{dist1} - dist2;
 
-.. note::
-
-    You can't subtract a quantity from a quantity point:
-
-    .. code-block::
-        :emphasize-lines: 3
-
-        Length auto dist1 = 2_q_m;
-        Length auto dist2 = 1_q_m;
-        auto res1 = dist1 - quantity_point{dist2};  // ERROR
-
 We can also subtract two quantity points.
 The result is a relative quantity of the same dimension:
 
@@ -111,7 +111,25 @@ The result is a relative quantity of the same dimension:
     Length auto dist2 = 1_q_m;
     Length auto res1 = quantity_point{dist1} - quantity_point{dist2};
 
-That's it! You can't multiply nor divide quantity points with anything else.
+.. note::
+
+    It is not allowed to:
+
+    - add quantity points
+    - subtract a quantity point from a quantity:
+    - multiply nor divide quantity points with anything else.
+
+    .. code-block::
+        :emphasize-lines: 3-5
+
+        Length auto dist1 = 2_q_m;
+        Length auto dist2 = 1_q_m;
+        auto res1 = quantity_point{dist1} + quantity_point{dist2};  // ERROR
+        auto res2 = dist1 - quantity_point{dist2};                  // ERROR
+        auto res3 = quantity_point{dist1} / 2_q_s;                  // ERROR
+
+Quantity Point Kinds
+++++++++++++++++++++
 
 The same restrictions of a quantity point with respect to its quantity
 apply to a quantity point kind with respect to its quantity kind.
@@ -185,7 +203,8 @@ an dimension's unnamed unit symbol is being printed in the text output.
 .. seealso::
 
     More information on how the :term:`recipe` affect the printed symbol
-    of unnamed unit can be found in the :ref:`Derived Unnamed Units` chapter.
+    of unnamed unit can be found in the :ref:`framework/units:Derived Unnamed Units`
+    chapter.
 
 It is important to mention here that beside text output the order and
 the number of elements in the `derived_dimension` definition does not
@@ -213,7 +232,8 @@ analysis in the library to work as expected.
     child class inherited from the instantiation of this `derived_dimension`
     class template. This is called a
     :abbr:`CRTP (Curiously Recurring Template Parameter)` Idiom and is used
-    in many places in this library to provide :ref:`The Downcasting Facility`.
+    in many places in this library to provide
+    :ref:`design/downcasting:The Downcasting Facility`.
     Hopefully if [P0847]_ will land in C++23 the additional CRTP-related
     template parameter will be removed from this definition.
 

docs/framework/quantities.rst

@@ -7,7 +7,6 @@ A :term:`quantity` is a concrete amount of a unit for a specified dimension
 with a specific representation and is represented in the library with a
 `quantity` class template.
 
-.. _quantity-construction:
 
 Construction
 ------------
@@ -198,6 +197,7 @@ The above code can be fixed in one of the below ways:
     inline constexpr auto km_per_h = km / h;
     Speed auto v = 220 / 2 * km_per_h;
 
+
 Dimension-specific Concepts
 ---------------------------
 
@@ -266,8 +266,8 @@ units like CGS.
 
 .. seealso::
 
-    Please refer to :ref:`avg_speed` example for more information on different
+    Please refer to :ref:`examples/avg_speed:avg_speed` example for more
-    kinds of interfaces supported by the library.
+    information on different kinds of interfaces supported by the library.
 
 
 Working With Constrained Deduced Quantity Types
@@ -295,8 +295,8 @@ but often we would like to know a specific type too. We have two options here:
 
 .. seealso::
 
-    More information on this subject can be found in :ref:`Conversions and Casting`
+    More information on this subject can be found in the
-    chapter.
+    :ref:`framework/conversions_and_casting:Conversions and Casting` chapter.
 
 
 Dimensionless Quantities
@@ -315,7 +315,7 @@ are zero".
 .. seealso::
 
     Reasoning for the above design is provided in
-    :ref:`Why a dimensionless quantity is not just an fundamental arithmetic type?`
+    :ref:`faq:Why a dimensionless quantity is not just an fundamental arithmetic type?`
 
 To simplify the usage of the dimensionless quantity a following concept and alias template
 are provided::
@@ -351,5 +351,6 @@ is expressed as a ratio of kilometers and megaparsecs.
 
 .. seealso::
 
-    More information on dimensionless quantities can be found in
+    More information on dimensionless quantities can be found in the
-    :ref:`Implicit conversions of dimensionless quantities`.
+    :ref:`framework/conversions_and_casting:Implicit conversions of dimensionless quantities`
+    chapter.

docs/framework/quantity_kinds.rst

@@ -7,16 +7,14 @@ A quantity kind is a quantity of more specific usage.
 It is represented in the library with a `quantity_kind` class template.
 
 
-.. _quantity-point-construction:
+Kind Creation
-
-Kind creation
 -------------
 
 We need a `kind` to represent the more specific usage of a quantity::
 
     struct radius : kind<radius, si::dim_length> {};
 
-Quantities of kind `radius` represent a radius.
+Quantities of kind ``radius`` represent a radius.
 They are clearly distinct from more generic usages of length quantities.
 
 
@@ -40,23 +38,26 @@ the value to the `quantity_kind` class template constructor::
         quantity_kind<radius, si::kilometre, double> d = 123 * km;  // ERROR
 
 
-Differences to quantity
+Differences To Quantity
 -----------------------
 
 Unlike `quantity`, the library provides:
 
 - no kinds, such as ``radius`` or ``width``, therefore
+
     * no UDLs or unit constants,
     * no kind-specific concepts, such as ``Radius``,
       (there's the generic `QuantityKind` and kind-specifiable `QuantityKindOf`),
+
 - a slightly different set of operations on quantity kinds
-  (see the :ref:`Dimensions` chapter).
+  (see the :ref:`framework/dimensions:Quantity Kinds` chapter).
 
-Quantity point kind
--------------------
 
-A quantity point kind is the analogous of a quantity point for quantity kinds.
+Quantity Point Kinds
-(see the :ref:`Quantity Points` chapter).
+--------------------
+
+A quantity point kind is the analogous of a quantity point for quantity kinds
+(see the :ref:`framework/quantity_points:Quantity Points` chapter).
 
 They are represented in the library with a `quantity_point_kind` class template.
 
@@ -67,6 +68,10 @@ First, we need a `point_kind` for a `kind`::
 
 Now ``x`` coordinates can be constructed::
 
-    quantity_point_kind<x_coordinate, si::metre, int> auto x_pos(123 * m);
+    quantity_point_kind<x_coordinate, si::metre, int> auto x_pos(123 * m); // QuantityPointKindOf<x_coordinate>
-    // `QuantityPointKindOf<x_coordinate>` with `x_pos.relative()`
+    auto x = x_pos.relative();   // quantity_kind<width, si::metre, int>(123 * m)
-    // equal to `quantity_kind<width, si::metre, int>(123 * m)`
+
+.. seealso::
+
+    Please refer to :ref:`examples/glide_computer:glide_computer` example for more
+    information on the quantity kinds usage.

docs/framework/quantity_points.rst

@@ -8,8 +8,6 @@ A quantity point is an absolute quantity with respect to zero
 `quantity_point` class template.
 
 
-.. _quantity-point-construction:
-
 Construction
 ------------
 
@@ -30,7 +28,7 @@ the value to the `quantity_point` class template explicit constructor::
         quantity_point<si::dim_length, si::kilometre, double> d = 123_q_km;  // ERROR
 
 
-Differences to quantity
+Differences To Quantity
 -----------------------
 
 Unlike `quantity`, the library provides:
@@ -40,4 +38,4 @@ Unlike `quantity`, the library provides:
 - no dimension-specific concepts, such as ``LengthPoint``
   (there's the dimension-agnostic `QuantityPoint`),
 - a more limited set of operations on quantity points
-  (see the :ref:`Dimensions` chapter)
+  (see the :ref:`framework/dimensions:Quantity Points` chapter)

docs/framework/text_output.rst

@@ -16,8 +16,7 @@ Output Streams
 
 .. tip::
 
-    The streaming support is provided via the ``<units/quantity_io.h>`` header
+    The streaming support is provided via the ``<units/quantity_io.h>`` header file.
-    file.
 
 The easiest way to print a quantity is to provide its object to the output
 stream::
@@ -55,6 +54,10 @@ over width, fill, and alignment::
 fmt::format
 -----------
 
+.. tip::
+
+    The text formatting support is provided via the ``<units/format.h>`` header file.
+
 The **mp-units** via ``fmt::format`` provides a fine-grained control over what
 and how is being printed on the text output.
 

docs/framework/units.rst

@@ -57,7 +57,8 @@ definitions of prefixed units using ``si::metre`` as a reference (i.e.
     child class inherited from the instantiation of this `named_unit`
     class template. This is called a
     :abbr:`CRTP (Curiously Recurring Template Parameter)` Idiom and is used
-    in many places in this library to provide :ref:`The Downcasting Facility`.
+    in many places in this library to provide
+    :ref:`design/downcasting:The Downcasting Facility`.
     Hopefully if [P0847]_ will land in C++23 the additional CRTP-related
     template parameter will be removed from this definition.
 
@@ -90,7 +91,7 @@ knows how to convert ``si::metre`` to ``si::centimetre`` and vice versa).
 
     More details on custom systems definitions and conversions between
     units of the same physical dimension can be found in the
-    :ref:`Custom Systems` chapter.
+    :ref:`use_cases/extensions:Custom Systems` chapter.
 
 
 Derived Units
@@ -399,5 +400,5 @@ type here instead.
 
 .. seealso::
 
-    To learn more about unknown units please refer to
+    To learn more about unknown units please refer to the
-    :ref:`Working with Unknown Dimensions and Their Units` chapter.
+    :ref:`use_cases/unknown_dimensions:Working with Unknown Dimensions and Their Units` chapter.

docs/introduction.rst

@@ -14,7 +14,7 @@ general facility for unit conversions.
 
 The library architecture has been designed with flexibility and extensibility
 in mind. The demonstrations of the ease of adding new dimensions, their units,
-and unit conversions are provided in the :ref:`Examples`.
+and unit conversions are provided in the :ref:`examples:Examples`.
 
 Open Source
 -----------
@@ -61,7 +61,7 @@ To achieve this goal several techniques are applied:
 - usage of C++20 concepts,
 - using strong types for framework entities (instead of type aliases),
 - limiting the number of template arguments to the bare minimum,
-- :ref:`The Downcasting Facility`.
+- :ref:`design/downcasting:The Downcasting Facility`.
 
 .. important::
 

docs/quick_start.rst

@@ -76,4 +76,4 @@ of basic library features::
 
 .. seealso::
 
-    You can find more code examples in the :ref:`Examples` chapter.
+    You can find more code examples in the :ref:`examples:Examples` chapter.

docs/reference/core/concepts.rst

@@ -14,7 +14,7 @@ Concepts
 
 .. concept:: template<typename T> Prefix
 
-    A concept matching a symbol prefix. Satisfied by all instantiations of :class:`prefix`.
+    A concept matching a symbol prefix. Satisfied by all instantiations of :struct:`prefix`.
 
 .. concept:: template<ratio R> UnitRatio
 
@@ -71,13 +71,13 @@ Concepts
 .. concept:: template<typename T> QuantityValue
 
     A concept matching types that can be used as a `Quantity` representation type. Satisfied
-    by types that match :expr:`(!Quantity<T>) && (!QuantityLike<T>) && (!WrappedQuantity<T>) && std::regular<T>`
+    by types that match ``(!Quantity<T>) && (!QuantityLike<T>) && (!WrappedQuantity<T>) && std::regular<T>``
     and satisfy one of the following:
 
-    - if :expr:`common_type_with<T, std::intmax_t>` is ``true``, then :expr:`std::common_type_t<T, std::intmax_t>`
+    - if ``common_type_with<T, std::intmax_t>`` is ``true``, then ``std::common_type_t<T, std::intmax_t>``
       must at least provide binary multiplication and division operators,
-    - otherwise, :expr:`T::value_type` must be valid, :expr:`common_type_with<T::value_type, std::intmax_t>` be
+    - otherwise, ``T::value_type`` must be valid, ``common_type_with<T::value_type, std::intmax_t>`` be
-      ``true``, and :expr:`std::common_type_t<T::value_type, std::intmax_t>` must at least provide binary
+      ``true``, and ``std::common_type_t<T::value_type, std::intmax_t>`` must at least provide binary
       multiplication and division operators with itself and ``T``.
 
 .. concept:: template<typename T> QuantityPoint
@@ -85,6 +85,26 @@ Concepts
     A concept matching all quantity points in the library. Satisfied by all instantiations of
     :class:`quantity_point`.
 
+.. concept:: template<typename T> Kind
+
+    A concept matching all kind types. Satisfied by all kind types derived from an specialization of
+    :class:`kind`.
+
+.. concept:: template<typename T> PointKind
+
+    A concept matching all point kind types. Satisfied by all point kind types derived from an specialization of
+    :class:`point_kind`.
+
+.. concept:: template<typename T> QuantityKind
+
+    A concept matching all quantity kinds in the library. Satisfied by all specializations of
+    :class:`quantity_kind`.
+
+.. concept:: template<typename T> QuantityPointKind
+
+    A concept matching all quantity point kinds in the library. Satisfied by all specializations of
+    :class:`quantity_point_kind`.
+
 .. concept:: template<typename Dim, template<typename...> typename DimTemplate> DimensionOfT
 
     A concept matching all dimensions being the instantiations derived from the provided dimension
@@ -95,7 +115,44 @@ Concepts
     A concept matching all quantities with a dimension being the instantiation derived from
     the provided dimension class template.
 
-.. concept:: template<typename T, typename Dim> QuantityOf
+.. concept:: template<typename Q, typename Dim> QuantityOf
 
     A concept matching all quantities with a dimension being the instantiation derived from
     the provided dimension type.
+
+.. concept:: template<typename Q1, typename Q2> QuantityEquivalentTo
+
+    A concept matching two equivalent quantities. Satisfied by quantities having equivalent dimensions.
+
+.. concept:: template<typename QP, typename Dim> QuantityPointOf
+
+    A concept matching all quantity points with a dimension being the instantiation derived from
+    the provided dimension type.
+
+.. concept:: template<typename QP1, typename QP2> QuantityPointEquivalentTo
+
+    A concept matching two equivalent quantity points. Satisfied by quantity points having equivalent
+    dimensions.
+
+.. concept:: template<typename QK, typename K> QuantityKindOf
+
+    A concept matching only quantity kinds of a specific kind.
+
+    :tparam QK: Quantity kind to verify.
+    :tparam K: Kind type to use for verification.
+
+.. concept:: template<typename QK1, typename QK2> QuantityKindEquivalentTo
+
+    A concept matching two equivalent quantity kinds. Satisfied by quantity kinds having equivalent kinds.
+ 
+.. concept:: template<typename QPK, typename PK> QuantityPointKindOf
+ 
+    A concept matching only quantity point kinds of a specific point kind.
+ 
+    :tparam QPK: Quantity point kind to verify.
+    :tparam PK: Point kind type to use for verification.
+
+.. concept:: template<typename QPK1, typename QPK2> QuantityPointKindEquivalentTo
+
+    A concept matching two equivalent quantity point kinds. Satisfied by quantity point kinds having
+    equivalent kinds.

docs/reference/core/downcasting.rst

@@ -1,6 +1,8 @@
 The Downcasting Facility
 ========================
 
+.. doxygenenum:: downcast_mode
+
 .. concept:: template<typename T> Downcastable
 
 .. doxygenstruct:: units::downcast_base

docs/reference/core/types.rst

@@ -6,6 +6,9 @@ Types
 
     types/quantity
     types/quantity_point
+    types/kind
+    types/quantity_kind
+    types/quantity_point_kind
     types/dimensions
     types/units
     types/prefixes

docs/reference/core/types/kind.rst

@@ -0,0 +1,8 @@
+Kinds
+=====
+
+.. doxygenstruct:: units::kind
+   :members:
+
+.. doxygenstruct:: units::point_kind
+   :members:

docs/reference/core/types/quantity_kind.rst

@@ -0,0 +1,6 @@
+Quantity Kind
+=============
+
+.. doxygenclass:: units::quantity_kind
+   :members:
+   :undoc-members:

docs/reference/core/types/quantity_point_kind.rst

@@ -0,0 +1,6 @@
+Quantity Point Kind
+===================
+
+.. doxygenclass:: units::quantity_point_kind
+   :members:
+   :undoc-members:

docs/usage.rst

@@ -125,7 +125,7 @@ downcast_mode
 
 **Defaulted to**: ``on``
 
-Specifies how :ref:`The Downcasting Facility` works:
+Specifies how :ref:`design/downcasting:The Downcasting Facility` works:
 
 - ``off`` - no downcasting at all
 - ``on`` - downcasting always forced -> compile-time errors in case of duplicated definitions

docs/use_cases/custom_representation_types.rst

@@ -217,10 +217,11 @@ operations.
 `treat_as_floating_point`
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In the :ref:`Conversions and Casting` chapter we learned that the conversions provided by the
+In the :ref:`framework/conversions_and_casting:Conversions and Casting` chapter we learned
-library's framework treat floating-point representation types differently than the integral
+that the conversions provided by the library's framework treat floating-point representation
-ones. This behavior can also be extended to the custom representation types with
+types differently than the integral ones. This behavior can also be extended to the custom
-`treat_as_floating_point` customization point which default definition is::
+representation types with `treat_as_floating_point` customization point which default
+definition is::
 
     template<QuantityValue Rep>
     inline constexpr bool treat_as_floating_point = std::is_floating_point_v<Rep>;
@@ -303,4 +304,5 @@ representation types with::
 .. seealso::
 
     For more examples of custom representation types usage please refer to the
-    :ref:`Linear Algebra vs. Quantities` chapter and the :ref:`measurement` example.
+    :ref:`use_cases/linear_algebra:Linear Algebra vs. Quantities` chapter and the
+    :ref:`examples/measurement:measurement` example.

docs/use_cases/extensions.rst

@@ -309,4 +309,5 @@ In such a situation the standalone system may be a better choice here.
 .. seealso::
 
     More information on extending the library can be found in the
-    :ref:`Using Custom Representation Types` chapter.
+    :ref:`use_cases/custom_representation_types:Using Custom Representation Types`
+    chapter.

docs/use_cases/linear_algebra.rst

@@ -61,7 +61,8 @@ types provided to a `quantity` class template.
 .. seealso::
 
     More information on providing custom representation types for `quantity` can be
-    found in the :ref:`Using Custom Representation Types` chapter.
+    found in the :ref:`use_cases/custom_representation_types:Using Custom Representation Types`
+    chapter.
 
 With this the above vector definitions can be rewritten as follows::
 
@@ -84,4 +85,4 @@ output:
 .. seealso::
 
     For more examples of Linear Algebra definition and operations please refer to
-    the :ref:`linear_algebra` example.
+    the :ref:`examples/linear_algebra:linear_algebra` example.

docs/use_cases/unknown_dimensions.rst

@@ -10,12 +10,14 @@ detail.
 What is an unknown dimension?
 -----------------------------
 
-As we learned in the :ref:`Dimensions` chapter, in most cases the result of multiplying
+As we learned in the :ref:`framework/dimensions:Dimensions` chapter, in most cases the result
-or dividing two quantities of specific dimensions is a quantity of yet another dimension.
+of multiplying or dividing two quantities of specific dimensions is a quantity of yet another
+dimension.
 
 If such a resulting dimension is predefined by the user (and a proper header file with its
-definition is included in the current translation unit) :ref:`The Downcasting Facility`
+definition is included in the current translation unit)
-will determine its type. The same applies to the resulting unit. For example:
+:ref:`design/downcasting:The Downcasting Facility` will determine its type.
+The same applies to the resulting unit. For example:
 
 .. code-block::
     :emphasize-lines: 1,7,9
@@ -83,7 +85,7 @@ following::
 .. seealso::
 
     Another good example of unknown dimension usage can be found in the
-    :ref:`box_example`::
+    :ref:`examples/box_example:box_example`::
 
         std::cout << "float rise rate = " << box.fill_level(measured_mass) / fill_time << '\n';
 

src/include/units/bits/basic_concepts.h

@@ -222,7 +222,7 @@ concept kind_impl_ =
 /**
  * @brief A concept matching all kind types
  *
- * Satisfied by all kind types derived from an specialization of :class:`kind`.
+ * Satisfied by all kind types derived from an specialization of @c kind.
  */
 template<typename T>
 concept Kind =
@@ -241,7 +241,7 @@ struct _point_kind_base;
 /**
  * @brief A concept matching all point kind types
  *
- * Satisfied by all point kind types derived from an specialization of :class:`point_kind`.
+ * Satisfied by all point kind types derived from an specialization of @c point_kind.
  */
 template<typename T>
 concept PointKind = kind_impl_<T, detail::_point_kind_base>;

src/include/units/bits/quantity_of.h

@@ -76,6 +76,11 @@ concept QuantityOfT = Quantity<Q> && DimensionOfT<typename Q::dimension, DimTemp
 template<typename Q, typename Dim>
 concept QuantityOf = Quantity<Q> && Dimension<Dim> && equivalent<typename Q::dimension, Dim>;
 
+/**
+ * @brief A concept matching two equivalent quantities
+ *
+ * Satisfied by quantities having equivalent dimensions.
+ */
 template<typename Q1, typename Q2>
 concept QuantityEquivalentTo = Quantity<Q1> && QuantityOf<Q2, typename Q1::dimension>;
 
@@ -88,6 +93,11 @@ concept QuantityEquivalentTo = Quantity<Q1> && QuantityOf<Q2, typename Q1::dimen
 template<typename QP, typename Dim>
 concept QuantityPointOf = QuantityPoint<QP> && Dimension<Dim> && equivalent<typename QP::dimension, Dim>;
 
+/**
+ * @brief A concept matching two equivalent quantity points
+ *
+ * Satisfied by quantity points having equivalent dimensions.
+ */
 template<typename QP1, typename QP2>
 concept QuantityPointEquivalentTo = QuantityPoint<QP1> && QuantityPointOf<QP2, typename QP1::dimension>;
 
@@ -100,6 +110,11 @@ concept QuantityPointEquivalentTo = QuantityPoint<QP1> && QuantityPointOf<QP2, t
 template<typename QK, typename K>
 concept QuantityKindOf = QuantityKind<QK> && Kind<K> && equivalent<typename QK::kind_type, K>;
 
+/**
+ * @brief A concept matching two equivalent quantity kinds
+ *
+ * Satisfied by quantity kinds having equivalent kinds.
+ */
 template<typename QK1, typename QK2>
 concept QuantityKindEquivalentTo = QuantityKind<QK1> && QuantityKindOf<QK2, typename QK1::kind_type>;
 
@@ -112,6 +127,11 @@ concept QuantityKindEquivalentTo = QuantityKind<QK1> && QuantityKindOf<QK2, type
 template<typename QPK, typename PK>
 concept QuantityPointKindOf = QuantityPointKind<QPK> && PointKind<PK> && equivalent<typename QPK::point_kind_type, PK>;
 
+/**
+ * @brief A concept matching two equivalent quantity point kinds
+ *
+ * Satisfied by quantity point kinds having equivalent kinds.
+ */
 template<typename QPK1, typename QPK2>
 concept QuantityPointKindEquivalentTo =
   QuantityPointKind<QPK1> && QuantityPointKindOf<QPK2, typename QPK1::point_kind_type>;

src/include/units/customization_points.h

@@ -78,7 +78,7 @@ struct quantity_values {
  * The type trait should provide the following nested type aliases: @c dimension, @c unit, @c rep,
  * and a static member function @c count(T) that will return the raw value of the quantity.
  * 
- * Usage example can be found in units/chrono.h header file.
+ * Usage example can be found in @c units/chrono.h header file.
  * 
  * @tparam T the type to provide support for
  */