Documentation for alias_unit added

docs/framework/units.rst

@@ -308,6 +308,32 @@ provided in the template parameter list after the derived dimension parameter,
 the library calculates the final ratio for this unit.
 
 
+Aliased Units
+-------------
+
+In order to make our life easier people tend to assign alternative/aliased names
+to some popular units. As an example we often use "tonne" instead of "megagram",
+"litre" instead of "cubic decimetre", or "hectare" instead of "square hectometre".
+
+This library provides facilities to define aliased names to already defined units
+with `alias_unit` class template::
+
+    namespace si {
+
+    struct litre : alias_unit<cubic_decimetre, "l", prefix> {};
+
+    }
+
+Also, it is possible to add prefixes to such aliased units with `prefixed_alias_unit`
+class template::
+
+    namespace si {
+
+    struct millilitre : prefixed_alias_unit<cubic_centimetre, milli, litre> {};
+
+    }
+
+
 Class Hierarchy
 ---------------
 
@@ -327,6 +353,8 @@ of a `scaled_unit` class template:
     [scaled_unit<UnitRatio, Unit>]<:-[named_scaled_unit<Child, Symbol, PrefixFamily, Ratio, Unit>]
     [scaled_unit<UnitRatio, Unit>]<:-[prefixed_unit<Child, Prefix, Unit>]
     [scaled_unit<UnitRatio, Unit>]<:-[deduced_unit<Child, Dimension, Unit, Unit...>]
+    [scaled_unit<UnitRatio, Unit>]<:-[alias_unit<Unit, Symbol, PrefixFamily>]
+    [scaled_unit<UnitRatio, Unit>]<:-[prefixed_alias_unit<Unit, Prefix, AliasUnit>]
 
 `scaled_unit` is a class template used exclusively by the library's framework
 and user should not instantiate it by him/her-self. However the user can sometimes

src/include/units/unit.h

@@ -172,6 +172,19 @@ struct deduced_unit : downcast_child<Child, detail::deduced_unit<Dim, U, URest..
 //   using prefix_family = PT;
 // };
 
+/**
+ * @brief An aliased named unit
+ *
+ * Defines a named alias for another unit. It is useful to assign alternative names and symbols
+ * to the already predefined units (i.e. "tonne" for "megagram").
+ * An alias unit may be used by other units defined with the prefix of the same type, unless
+ * no_prefix is provided for PT template parameter (in such a case it is impossible to define
+ * a prefix unit based on this one).
+ *
+ * @tparam U Unit for which an alias is defined
+ * @tparam Symbol a short text representation of the unit
+ * @tparam PT no_prefix or a type of prefix family
+ */
 template<Unit U, basic_symbol_text Symbol, PrefixFamily PT>
 struct alias_unit : U {
   static constexpr bool is_named = true;
@@ -179,6 +192,17 @@ struct alias_unit : U {
   using prefix_family = PT;
 };
 
+/**
+ * @brief A prefixed alias unit
+ *
+ * Defines a new unit that is an alias for a scaled version of another unit by the provided
+ * prefix. It is only possible to create such a unit if the given prefix type matches the one
+ * defined in a reference unit.
+ *
+ * @tparam U Unit for which an alias is defined
+ * @tparam P prefix to be appied to the reference unit
+ * @tparam AU reference alias unit
+ */
 // TODO gcc bug: 95015
 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95015
 // template<Unit U, Prefix P, AliasUnit AU>