[libcalamares] Document NamedSuffix

- Add more constructors
 - Make the table-constructor public, no need to force
   subclassing on everyone
 - Declare some useful API
 - Document the bits.

src/libcalamares/utils/NamedSuffix.h

@@ -17,6 +17,23 @@
  */
 
 /** @brief Support for unit-suffixed values.
+ *
+ * This combines a value with an (enum) unit indicating what kind
+ * of value it is, e.g. 10 meters, or 64 pixels. Includes simple
+ * parsing support for the values written as strings like <value><unit>,
+ * e.g. "10m" or "64px".
+ *
+ * When a suffixed unit value needs validation, define an isValid()
+ * method; similarly for simple construction from a string (with a fixed
+ * table of suffixes). Typical use then looks like:
+ *
+ * class MyUnit : public NamedSuffix<MyUnitEnum, MyUnitEnum::None>
+ * {
+ * public:
+ *      using NamedSuffix::NamedSuffix;  // Keep existing constructors
+ *      MyUnit( const QString& s );
+ *      bool isValid() const;
+ * } ;
  */
 
 #ifndef LIBCALAMARES_NAMEDSUFFIX_H
@@ -24,24 +41,34 @@
 
 #include "NamedEnum.h"
 
-template<typename T, T none>
+/** @brief Template that takes the enum type to work with and a special none-enum. */
+template<typename T, T _none>
 class NamedSuffix
 {
 public:
     using unit_t = T;
 
+    static constexpr unit_t none = _none;
+
+    /** @brief Empty value. */
     NamedSuffix()
         : m_value(0)
         , m_unit( none )
     {
     }
 
-    int value() const { return m_value; }
-    T unit() const { return m_unit; }
-
-    bool isValid() const { return m_unit != none; }
+    /** @brief Specific value and unit. */
+    NamedSuffix( int value, unit_t unit )
+        : m_value( value )
+        , m_unit( unit )
+    {
+    }
 
-protected:
+    /** @brief Construct value and unit from string.
+     *
+     * This parses the given string @p s by comparing with the suffixes
+     * in @p table and uses the first matching suffix as the unit.
+     */
     NamedSuffix( const NamedEnumTable<T>& table, const QString& s )
         : NamedSuffix()
     {
@@ -54,8 +81,27 @@ protected:
             }
     }
 
+
+    /** @brief Construct value from string.
+     *
+     * This is not defined in the template, because it should probably
+     * delegate to the constructor above with a fixed table.
+     */
+    NamedSuffix( const QString& s );
+
+    int value() const { return m_value; }
+    unit_t unit() const { return m_unit; }
+
+    /** @brief Check that a value-unit combination is valid.
+     *
+     * This is not defined in the template, because validity (e.g.
+     * range of acceptable values) depends on the kind of unit.
+     */
+    bool isValid() const;
+
+protected:
     int m_value;
-    T m_unit;
+    unit_t m_unit;
 };