niknaks.config

- Updated header doc

PAckage

- Added import

source/niknaks/config.d

@@ -1,8 +1,16 @@
+/** 
+ * Configuration management
+ *
+ * Configuration entries and
+ * a registry in which to
+ * manage a set of them
+ *
+ * Authors: Tristan Brice Velloza Kildaire (deavmi)
+ */
 module niknaks.config;
 
 import std.string : format;
 
-
 version(unittest)
 {
     import std.stdio : writeln;
@@ -59,9 +67,19 @@ public struct ConfigEntry
     private ConfigValue value;
     private ConfigType type;
 
-    // If set at all
+    /** 
+     * A flag which is used to
+     * know if a value has been
+     * set at all. This helps
+     * with the fact that 
+     * an entry can be constructed
+     * without having a value set
+     */
     private bool isSet = false;
 
+    /** 
+     * Ensures a value is set
+     */
     private void ensureSet()
     {
         if(!this.isSet)
@@ -70,6 +88,10 @@ public struct ConfigEntry
         }
     }
 
+    /**
+     * Marks this entry as having
+     * a value set
+     */
     private void set()
     {
         this.isSet = true;
@@ -79,6 +101,14 @@ public struct ConfigEntry
     // @disable
     // private this();
 
+    /** 
+     * Constructs a new `ConfigEntry`
+     * with the given value and type
+     *
+     * Params:
+     *   value = the value itself
+     *   type = the value's type
+     */
     private this(ConfigValue value, ConfigType type)
     {
         this.value = value;
@@ -87,6 +117,14 @@ public struct ConfigEntry
         set();
     }
 
+    /** 
+     * Creates a new configuration entry
+     * containing text
+     *
+     * Params:
+     *   text = the text
+     * Returns: a `ConfigEntry`
+     */
     public static ConfigEntry ofText(string text)
     {
         ConfigValue tmp;
@@ -94,6 +132,14 @@ public struct ConfigEntry
         return ConfigEntry(tmp, type.TEXT);
     }
 
+    /** 
+     * Creates a new configuration entry
+     * containing an integer
+     *
+     * Params:
+     *   i = the integer
+     * Returns: a `ConfigEntry`
+     */
     public static ConfigEntry ofNumeric(int i)
     {
         ConfigValue tmp;
@@ -101,6 +147,14 @@ public struct ConfigEntry
         return ConfigEntry(tmp, type.NUMERIC);
     }
 
+    /** 
+     * Creates a new configuration entry
+     * containing a flag
+     *
+     * Params:
+     *   flag = the flag
+     * Returns: a `ConfigEntry`
+     */
     public static ConfigEntry ofFlag(bool flag)
     {
         ConfigValue tmp;
@@ -108,6 +162,14 @@ public struct ConfigEntry
         return ConfigEntry(tmp, type.FLAG);
     }
 
+    /** 
+     * Creates a new configuration entry
+     * containing a textual array
+     *
+     * Params:
+     *   array = the textual array
+     * Returns: a `ConfigEntry`
+     */
     public static ConfigEntry ofArray(string[] array)
     {
         ConfigValue tmp;
@@ -115,16 +177,40 @@ public struct ConfigEntry
         return ConfigEntry(tmp, type.ARRAY);
     }
 
+    /** 
+     * Returns the type of the
+     * entry's value
+     *
+     * Returns: a `ConfigType`
+     */
     public ConfigType getType()
     {
         return this.type;
     }
 
+    /** 
+     * Ensures the requested type
+     * matches the current type
+     * set
+     *
+     * Params:
+     *   requested = the requested
+     * type
+     * Returns: `true` if the types
+     * are the same, `false` otherwise
+     */
     private bool ensureTypeMatch0(ConfigType requested)
     {
         return getType() == requested;
     }
 
+    /** 
+     * A version of the type
+     * matcher but which throws
+     * an exception on type mismatch
+     *
+     * See_Also: `ensureTypeMatch0(ConfigType)`
+     */
     private void ensureTypeMatch(ConfigType requested)
     {
         if(!ensureTypeMatch0(requested))
@@ -133,6 +219,15 @@ public struct ConfigEntry
         }
     }
 
+    /** 
+     * Obtains the numeric value
+     * of this entry
+     *
+     * Returns: an integer
+     * Throws: ConfigException if
+     * the type of the value in this
+     * entry is not numeric
+     */
     public int numeric()
     {
         ensureSet;
@@ -140,6 +235,15 @@ public struct ConfigEntry
         return this.value.integer;
     }
 
+    /** 
+     * Obtains the textual array
+     * value of this entry
+     *
+     * Returns: a `string[]`
+     * Throws: ConfigException if
+     * the type of the value in this
+     * entry is not a textual array
+     */
     public string[] array()
     {
         ensureSet;
@@ -147,11 +251,23 @@ public struct ConfigEntry
         return this.value.textArray;
     }
 
+    /** 
+     * See_Also: `array()`
+     */
     public string[] opSlice()
     {
         return array();
     }
 
+    /** 
+     * Obtains the flag value
+     * of this entry
+     *
+     * Returns: a `string[]`
+     * Throws: ConfigException if
+     * the type of the value in this
+     * entry is not a flag
+     */
     public bool flag()
     {
         ensureSet;
@@ -159,16 +275,31 @@ public struct ConfigEntry
         return this.value.flag;
     }
 
+    /** 
+     * See_Also: `flag()`
+     */
     public bool isTrue()
     {
         return flag() == true;
     }
 
+    /** 
+     * See_Also: `flag()`
+     */
     public bool isFalse()
     {
         return flag() == false;
     }
 
+    /** 
+     * Obtains the text value
+     * of this entry
+     *
+     * Returns: a string
+     * Throws: ConfigException if
+     * the type of the value in this
+     * entry is not a string
+     */
     public string text()
     {
         ensureSet;
@@ -176,6 +307,15 @@ public struct ConfigEntry
         return this.value.text;
     }
 
+    /** 
+     * Obtains the value of this
+     * configuration entry dependant
+     * on the requested casting type
+     * and matching that to the supported
+     * types of the configuration entry
+     *
+     * Returns: a value of type `T`
+     */
     public T opCast(T)()
     {
         static if(__traits(isSame, T, bool))

source/niknaks/package.d

@@ -41,4 +41,13 @@ public import niknaks.debugging;
  * Useful data structures
  * that are templatised
  */
-public import niknaks.containers;
+public import niknaks.containers;
+
+/** 
+ * Configuration management
+ *
+ * Configuration entries and
+ * a registry in which to
+ * manage a set of them
+ */
+public import niknaks.config;