configtoolkit 1.0.6 → 1.0.7

data/History.txt

@@ -1,3 +1,6 @@
+=== 1.0.7 / 2008-05-13
+Finish the code comments and code cleanup.
+
 === 1.0.6 / 2008-05-13
 Improve the code comments.
 

data/Manifest.txt

@@ -17,6 +17,6 @@ test/bad_config.yaml
 test/contained_sample.yaml
 test/firewall.yaml
 test/machines.yaml
-test/sample.ruby_yaml_types.yaml
-test/sample.standard_yaml_types.yaml
+test/sample.ruby_yaml_classes.yaml
+test/sample.standard_yaml_classes.yaml
 test/webserver.yaml

data/Rakefile

@@ -7,7 +7,7 @@ require 'hoe'
 
 $stderr = STDERR
 
-Hoe.new('configtoolkit', "1.0.6") do |p|
+Hoe.new('configtoolkit', "1.0.7") do |p|
   p.remote_rdoc_dir = 'rdoc'
   p.developer('DesigningPatterns', 'technical.inquiries@designingpatterns.com')
 end

data/lib/configtoolkit/baseconfig.rb

@@ -40,10 +40,11 @@ class BaseConfig
   #
   # This class represents the specification for a parameter.  Right now,
   # a parameter specification consists of:
-  # 1.) The parameter name (Symbol)
-  # 2.) The parameter value class (Class)
-  # 3.) Whether or not the parameter is required
-  # 4.) If the parameter is not required, a default value
+  # * The parameter name (Symbol)
+  # * The parameter value class (Class); values must be instances of this
+  #   class or a child class.
+  # * Whether or not the parameter is required
+  # * If the parameter is not required, a default value
   #
   class ParamSpec
     attr_reader :name
@@ -52,20 +53,21 @@ class BaseConfig
 
     # 
     # ====Description:
-    # 
+    # This constructs a Paramspec for parameter name and value
+    # of class value_class.  If is_required, then the parameter is
+    # required; otherwise, the parameter is optional with a default
+    # value of default_value.
     # 
     # ====Parameters:
     # [name]
-    #      ?
+    #      The name of the parameter
     # [value_class]
-    #      ?
+    #      The class of the parameter's values
     # [is_required]
-    #      ?
+    #      Whether or not the parameter must be set in a configuration file
     # [default_value]
-    #      ?
-    # 
-    # ====Returns:
-    # 
+    #      If the parameter need not be set in a configuration file
+    #      (!is_required), the value it defaults to if it's not specified.
     # 
     def initialize(name, value_class, is_required, default_value)
       @name = name
@@ -77,12 +79,10 @@ class BaseConfig
       end
     end
 
-    # 
-    # ====Description:
-    # 
     # 
     # ====Returns:
-    # 
+    # true if and only if the parameter must be set in a configuration
+    # file; false otherwise.
     # 
     def is_required?
       return @is_required
@@ -93,37 +93,52 @@ class BaseConfig
   # The indentation used to indicate nesting when printing out
   # a BaseConfig.
   #
-  NESTING_INDENT = "  " * 2
+  NESTING_INDENT = " " * 4
 
   #
   # Create accessors for some class instance variables;
-  # these variables will contain the structure of each
-  # BaseConfig child class (which parameters are supported,
-  # which are required, etc.).
+  # these variables will contain the specifications for a given
+  # BaseConfig child class (what parameters are specified, which
+  # parameters are required, etc).
   #
-  # The config parameters are stored in a list (@param_list) for ordered
-  # access (we want to print them out in the order in which they
-  # were added to the config) and in a hash (@param_hash), for fast lookups
-  # (as we want to check whether a parameter that we read from a file
-  # is supported by the class).
+  # The parameter specifications are stored in a list (@param_spec_list)
+  # for ordered access (we want to print them out in the order in which they
+  # were specified in the BaseConfig child class, for instance) and
+  # in a hash (@param_hash), for fast lookups (as we want to check whether
+  # a parameter that we read from a file is supported by the class).
   #
   class << self
+    #
+    # This is an Array (class instance variable) containing the parameter
+    # specifications (ParamSpecs) in the order in which they were specified
+    # in the BaseConfig child class.
+    #
     attr_reader :param_spec_list
+
+    #
+    # This is a Hash (class instance variable) mapping
+    # paramater names (Symbols) to parameter specifications (ParamSpecs)
+    #
     attr_reader :param_spec_lookup_table
+
+    #
+    # This is an Integer (class instance variable) containing the length
+    # of the longest parameter name.  This is used to line up the output
+    # when printing out an instance.
+    #
     attr_reader :longest_param_name_length
-    attr_reader :required_params
   end
 
   # 
   # ====Description:
-  # 
+  # This is BaseConfig's implementation of the inherited hook, which is
+  # called by the Ruby interpreter whenever BaseConfig is extended.  This
+  # function initializes the class instance variables of the new
+  # child class.
   # 
   # ====Parameters:
   # [child_class]
-  #      ?
-  # 
-  # ====Returns:
-  # 
+  #      The new child class
   # 
   def self.inherited(child_class)
     #
@@ -133,52 +148,68 @@ class BaseConfig
       @param_spec_list = []
       @param_spec_lookup_table = {}
       @longest_param_name_length = 0
-      @required_params = Set.new()
     end
   end
 
-  # 
+  #
   # ====Description:
-  # 
+  # This class method adds a new parameter to a BaseConfig child
+  # class (it should be called within the body of the child class'
+  # definition).  The new parameter has name name and has values
+  # of class value_class (or one of value_class' child classes).
+  # The parameter must be set in a configuration file if
+  # is_required is true; if !is_required, then default_value is the
+  # value of the parameter if it's not set in a configuration file.
+  #
+  # This method optionally accepts a block (validate_value_block), which,
+  # if present, is called with the new value for the parameter before setting
+  # the parameter with the new value, allowing custom validation
+  # code to be executed (if this validation fails, then raise_error should
+  # be called inside of the block).
+  #
+  # This method is not meant to be called directly; users instead should
+  # call add_required_param or add_optional_param.
   # 
   # ====Parameters:
   # [name]
-  #      ?
+  #      The name of the parameter
   # [value_class]
-  #      ?
+  #      The parent class of the parameter's values
   # [is_required]
-  #      ?
+  #      Whether or not the parameter must be specified in a
+  #      configuration file.
   # [default_value]
-  #      ?
+  #      If !is_required, then the default value of the parameter if it's
+  #      not specified in a configuration file.
   # [validate_value_block]
-  #      ?
-  # 
-  # ====Returns:
-  # 
+  #      An optional block that, if present, is called to validate a new
+  #      value for the parameter before setting the parameter to the new
+  #      value.
   # 
   def self.add_param(name,
                      value_class,
                      is_required,
                      default_value,
-                     &validate_value_block)
+                     &validate_value_block) #:doc:
     param_spec = ParamSpec.new(name, value_class, is_required, default_value)
     @param_spec_list.push(param_spec)
     @param_spec_lookup_table[name] = param_spec
 
     #
-    # Define the setter method with a string passed to class_eval rather
-    # than a block, so as to avoid the need to access the reflectoin APIs
-    # when the setter actually is called.
+    # Define the getter and setter methods with a string passed to
+    # class_eval rather than a block, so as to avoid the need to access
+    # the reflectoin APIs when the setter actually is called.
     #
     # Note that the setter will call load_value_impl() on any value
     # that it is passed; this ensures that data specified programatically
-    # gets processed the same way as that sourced from files.
+    # gets processed in the same way as that sourced from files.
     #
     # There is a bit of hackiness to get the specified value class; the
     # value class is retrieved from a lookup table rather
-    # than being sourced from value_class.  The reason for this is that the
-    # value_class argument could be an anonymous class without a valid name
-    # and so cannot safely be expanded in a string.  Instead, we'll access a
+    # than being sourced from the value_class argument.
+    # The reason for this is that the value_class argument could be
+    # an anonymous class without a valid name and so cannot safely
+    # be expanded in a string.  Instead, we'll access a
     # variable storing this class from the param_spec_lookup_table.
     #
     methods = String.new()
@@ -189,6 +220,7 @@ class BaseConfig
     methods << "  loaded_value = load_value_impl(\"#{name}\", value_class, value)\n"
     if(validate_value_block != nil)
       validate_value_method = "validate_#{name}_value".to_sym()
+      define_method(validate_value_method, &validate_value_block)
       methods << "  begin\n"
       methods << "    #{validate_value_method}(value)\n"
       methods << "  rescue Error => e\n"
@@ -202,76 +234,57 @@ class BaseConfig
 
     class_eval(methods)
 
-    if(validate_value_block != nil)
-      define_method(validate_value_method, &validate_value_block)
-    end
-
     name_str = name.to_s
     if(name_str.length > @longest_param_name_length)
       @longest_param_name_length = name_str.length
     end
-
-    if(is_required)
-      @required_params.add(name)
-    end
   end
   private_class_method :add_param
 
   # 
   # ====Description:
-  # 
+  # This is a wrapper around add_param that passes is_required = true.
   # 
   # ====Parameters:
-  # [name]
-  #      ?
-  # [value_class]
-  #      ?
-  # [validate_value_block]
-  #      ?
-  # 
-  # ====Returns:
-  # 
+  # See add_param's parameter list.
   # 
   def self.add_required_param(name,
                               value_class,
-                              &validate_value_block)
+                              &validate_value_block) #:doc:
     add_param(name, value_class, true, nil, &validate_value_block)
   end
   private_class_method :add_required_param
 
   # 
   # ====Description:
-  # 
+  # This is a wrapper around add_param that passes is_required = false and
+  # default_value = default_value.
   # 
   # ====Parameters:
-  # [name]
-  #      ?
-  # [value_class]
-  #      ?
-  # [default_value]
-  #      ?
-  # [validate_value_block]
-  #      ?
-  # 
-  # ====Returns:
-  # 
+  # See add_param's parameter list.
   # 
   def self.add_optional_param(name,
                               value_class,
                               default_value,
-                              &validate_value_block)
+                              &validate_value_block) #:doc:
     add_param(name, value_class, false, default_value, &validate_value_block)
   end
   private_class_method :add_optional_param
 
-  attr_reader :containing_object_name
+  #
+  # This is a String (instance variable) containing the name of the object that
+  # contains this instance's configuration.  For example, if
+  # all of this instance's configuration is under production and
+  # webserver, then the containing_object_name would be
+  # 'production.webserver'.
+  #
+  attr_accessor :containing_object_name
+  protected :containing_object_name= # This is NOT part of the public interface
 
   # 
   # ====Description:
-  # 
-  # 
-  # ====Returns:
-  # 
+  # This constructs a BaseConfig with no parameters set (all parameters
+  # initially have a nil value).
   # 
   def initialize
     @containing_object_name = ""
@@ -284,19 +297,29 @@ class BaseConfig
 
   # 
   # ====Description:
-  # 
+  # This method enforces the BaseConfig's specifications.  In particular,
+  # it:
+  # * Checks hat all required parameters have been set.  If a required
+  #   parameter is missing, then this method raises an Error.
+  # * Sets all optional parameters without values to their
+  #   default values.
+  # * Calls validate_all_values, if this exists.
+  #
+  # This method is called at the end of a load operation (verifying that
+  # a valid configuration was loaded from a reader) and before a dump operation
+  # (verifying that a valid configuration will be dumped).  The operation_name
+  # parameter is a String containing the name of the operation calling
+  # this method; this String is used in Error messages.
   # 
   # ====Parameters:
   # [operation_name]
-  #      ?
-  # 
-  # ====Returns:
-  # 
+  #      A String containing the name of the operation calling this
+  #      method ("load" or "dump", for example)
   # 
   def enforce_specs(operation_name)
     #
     # Iterate through the parameters without values.  If any are
-    # required parameters, then throw (after completing the
+    # required parameters, then raise (after completing the
     # iteration in order to get the full list of missing
     # parameters).  Otherwise, set all optional, missing
     # parameters to their default values.
@@ -308,18 +331,23 @@ class BaseConfig
         if(param_spec.is_required?)
           missing_params.push(param_spec.name)
         else
+          #
+          # Even the default values are set through the setter.
+          #
           send("#{param_spec.name}=", param_spec.default_value)
         end
       end
     end
 
     if(!missing_params.empty?)
+      if(@containing_object_name.empty?)
+        param_prefix = ""
+      else
+        param_prefix = "#{@containing_object_name}."
+      end
+
       missing_param_spec_list = missing_params.map do |param_name|
-        if(@containing_object_name.empty?)
-          next "#{param_name}"
-        else
-          next "#{@containing_object_name}.#{param_name}"
-        end
+        "#{param_prefix}#{param_name}"
       end
 
       raise Error, "missing parameter(s): #{missing_param_spec_list.join(", ")}"
@@ -329,6 +357,10 @@ class BaseConfig
       begin
         validate_all_values()
       rescue Error => e
+        #
+        # Rescue the error, add some information to the error message, and
+        # throw a repackaged error.
+        #
         message = "#{self.class}#validate_all_values #{operation_name} error"
 
         if(!@containing_object_name.empty?)
@@ -345,23 +377,31 @@ class BaseConfig
   #
   # ====Description:
   # Because the to_s in Ruby 1.8 for the Array and Hash classes
-  # are horrible...
+  # are horrible...  This method returns a readable String representation
+  # of value, recursively expanding the contents of Array and Hash
+  # value arguments and otherwise returning value.to_s.  This is
+  # called by construct_error_message in order to construct a nicely formatted
+  # error message.
   # 
   # ====Parameters:
   # [value]
-  #      ?
+  #      The object for which to return a String representation
   # 
   # ====Returns:
-  # 
+  # A nicely formatted String representation of value
   # 
   def construct_value_str(value)
     if(value.is_a?(Array))
+      #
+      # Recursively call construct_value_str for each Array element,
+      # surrounding the element strings in brackets.
+      #
       str = "["
 
       value.each_with_index do |element, index|
         str << construct_value_str(element)
 
-        if(index != (value.size - 1))
+        if(index < (value.size - 1))
           str << ", "
         end
       end
@@ -369,12 +409,16 @@ class BaseConfig
       str << "]"
       return str
     elsif(value.is_a?(Hash))
+      #
+      # Recursively call construct_value_str for each Hash element,
+      # surrounding the element strings in braces.
+      #
       str = "{"
 
       value.each_with_index do |key_value, index|
         str << "#{construct_value_str(key_value[0])}=>#{construct_value_str(key_value[1])}"
 
-        if(index != (value.size - 1))
+        if(index < (value.size - 1))
           str << ", "
         end
       end
@@ -389,57 +433,62 @@ class BaseConfig
 
   # 
   # ====Description:
-  # 
+  # This method returns an error message for an error (described by
+  # reason) that occurred while setting parameter param_name with
+  # value value.
   # 
   # ====Parameters:
   # [param_name]
-  #      ?
+  #      The parameter being set when the error occurred (String)
+  #      This need not be a "real" parameter value; it also can be
+  #      an element in an Array value (i.e., the 3rd element of Array
+  #      parameter servers will be passed as "servers[2]").
   # [value]
-  #      ?
-  # [message]
-  #      ?
+  #      The parameter value that caused the error
+  # [reason]
+  #      The reason for the error (String)
   # 
   # ====Returns:
+  # An error message that includes the parameter name, the problem
+  # parameter value, and the error description.
   # 
-  # 
-  def construct_error_message(param_name, value, message)
+  def construct_error_message(param_name, value, reason)
     if(@containing_object_name.empty?)
-      full_param_name = ""
+      full_param_name = "#{param_name}"
     else
-      full_param_name = "#{@containing_object_name}."
+      full_param_name = "#{@containing_object_name}.#{param_name}"
     end
 
-    full_param_name += param_name
-
-    return "error setting parameter #{full_param_name} with value #{construct_value_str(value)}: #{message}."
+    return "error setting parameter #{full_param_name} with value #{construct_value_str(value)}: #{reason}."
   end
   private :construct_error_message
 
   # 
   # ====Description:
-  # 
+  # This method raises an Error with message reason.  It is meant to
+  # be called from user-defined parameter validation blocks.  This is
+  # a Hotel California type of call; it does not return.
   # 
   # ====Parameters:
-  # [message]
-  #      ?
-  # 
-  # ====Returns:
+  # [reason]
+  #      The reason for the error
   # 
-  # 
-  def raise_error(message)
-    raise Error, message, caller()
+  def raise_error(reason)
+    raise Error, reason, caller()
   end
 
   # 
   # ====Description:
-  # 
+  # Equality operator for BaseConfig; this iterates through the
+  # specified parameters and compares the parameter values of
+  # self and rhs using the equality operator of the parameter values.
   # 
   # ====Parameters:
   # [rhs]
-  #      ?
+  #      The instance to compare with self
   # 
   # ====Returns:
-  # 
+  # True if and only if the values of self and rhs are equal
   # 
   def ==(rhs)
     if(rhs == nil)
@@ -457,24 +506,24 @@ class BaseConfig
 
   # 
   # ====Description:
-  # 
+  # This method returns a dump of parameter value value.
+  # It recursively calls itself and dump_impl to handle
+  # Array elements and BaseConfig instances.
   # 
   # ====Parameters:
-  # [value_class]
-  #      ?
   # [value]
-  #      ?
+  #      The parameter value to dump
   # 
   # ====Returns:
+  # A dump of value
   # 
-  # 
-  def dump_value_impl(value_class, value)
-    if(value_class < BaseConfig)
+  def dump_value_impl(value)
+    if(value.class < BaseConfig)
       return value.dump_impl({})
-    elsif(value_class < ConstrainedArray)
+    elsif(value.class == Array)
       dumped_array = []
       value.each do |element|
-        dumped_array.push(dump_value_impl(value_class.element_class, element))
+        dumped_array.push(dump_value_impl(element))
       end
       return dumped_array
     else
@@ -485,14 +534,20 @@ class BaseConfig
 
   # 
   # ====Description:
-  # 
+  # This method dumps self into containing_object_hash; that is,
+  # it adds entries to containing_object_hash for each parameter.
+  # An entry's key is the parameter name (as a String), and the value is
+  # the parameter value.  The method returns containing_object_hash
+  # after the dump.  Before dumping everything, this method calls
+  # enforce_specs in order to ensure that valid data is being
+  # dumped.
   # 
   # ====Parameters:
   # [containing_object_hash]
-  #      ?
+  #      The hash into which to dump self
   # 
   # ====Returns:
-  # 
+  # containing_object_hash after the dump
   # 
   def dump_impl(containing_object_hash)
     #
@@ -502,7 +557,7 @@ class BaseConfig
     enforce_specs("dump")
 
     self.class.param_spec_list.each do |param_spec|
-      containing_object_hash[param_spec.name.to_s] = dump_value_impl(param_spec.value_class, send(param_spec.name))
+      containing_object_hash[param_spec.name.to_s] = dump_value_impl(send(param_spec.name))
     end
 
     return containing_object_hash
@@ -511,14 +566,16 @@ class BaseConfig
 
   # 
   # ====Description:
-  # 
+  # This method dumps self to writer.  That is, it constructs
+  # a Hash containing entries for the containing object (and,
+  # in the the most nested containing object entry, entries for the
+  # paramters) and passes the Hash to the write method of writer.  The
+  # configuration's data is checked against its specifications
+  # before anything is dumped.
   # 
   # ====Parameters:
   # [writer]
-  #      ?
-  # 
-  # ====Returns:
-  # 
+  #      The writer to which to dump
   # 
   def dump(writer)
     dump_hash = {}
@@ -536,31 +593,46 @@ class BaseConfig
 
   # 
   # ====Description:
-  # 
+  # This method validates and returns a parameter value of class value_class
+  # for parameter param_name (String) from raw_value.  The logic in this
+  # method is a bit gnarly.  In particular, it needs to:
+  # * Construct BaseConfig child instances from Hash values, recursively
+  #   loading these with load_impl.
+  # * Recursively call itself on Array elements in order to construct
+  #   Array parameter values.
+  # * Load true and false values for Boolean parameters
+  # * Convert String values to a small number of non-String parameter
+  #   types, including Integers, Floats, Booleans, Pathnames, and URIs.
+  #   This is done because not all reader classes will read different
+  #   types from files and so BaseConfig has to do some lexical casting.
   # 
   # ====Parameters:
   # [param_name]
-  #      ?
+  #      The name of the parameter whose value is being loaded (String).
+  #      This need not be a "real" parameter value; it also can be
+  #      an element in an Array value (i.e., the 3rd element of Array
+  #      parameter servers will be passed as "servers[2]").
   # [value_class]
-  #      ?
-  # [value]
-  #      ?
+  #      The class of the parameter's values (Class)
+  # [raw_value]
+  #      The raw value from which to load the parameter value
   # 
   # ====Returns:
+  # A parameter value of class value_class for param_name loaded from raw_value
   # 
-  # 
-  def load_value_impl(param_name, value_class, value)
-    if(value.class <= value_class)
+  def load_value_impl(param_name, value_class, raw_value)
+    if(raw_value.class <= value_class)
       #
-      # If the ConfigReader has returned a value of the same class as
+      # If the reader has returned a value of the same class as
       # was specified for that parameter (or a child class of the specified
       # class), then just return the value.
       #
-      return value
-    elsif((value_class < BaseConfig) && (value.class == Hash))
+      return raw_value
+    elsif((value_class < BaseConfig) && (raw_value.class == Hash))
       #
-      # If we're looking for a BaseConfig child and have a hash, then
-      # construct the child with the hash.
+      # If we're looking for a BaseConfig child and have a Hash, then
+      # construct the BaseConfig child with the Hash by (recursively) calling
+      # load_impl.
       #
       child_config = value_class.new()
 
@@ -570,91 +642,92 @@ class BaseConfig
         nested_containing_object_name = "#{@containing_object_name}.#{param_name}"
       end
 
-      child_config.load_impl(value, nested_containing_object_name)
+      child_config.containing_object_name = nested_containing_object_name
+      child_config.load_impl(raw_value)
       return child_config
-    elsif((value_class < ConstrainedArray) && (value.class == Array))
+    elsif((value_class < ConstrainedArray) && (raw_value.class == Array))
       #
       # If we're looking for a ConstrainedArray and have a Ruby Array, then
       # iterate over each element of the Ruby Array and recursively
-      # load it.
+      # load it with load_value_impl.
       #
-      value.each_with_index do |element, index|
-        value[index] = load_value_impl("#{param_name}[#{index}]", value_class.element_class, element)
+      value = []
+
+      raw_value.each_with_index do |element, index|
+        value.push(load_value_impl("#{param_name}[#{index}]", value_class.element_class, element))
       end
 
       if((value_class.min_num_elements != nil) &&
          (value.length < value_class.min_num_elements))
         message = "the number of elements (#{value.length}) is less than the specified "
         message << "minimum number of elements (#{value_class.min_num_elements})"
-        raise Error, construct_error_message(param_name, value, message)
+        raise Error, construct_error_message(param_name, raw_value, message)
       end
       
       if((value_class.max_num_elements != nil) &&
          (value.length > value_class.max_num_elements))
         message = "the number of elements (#{value.length}) is greater than the specified "
         message << "maximum number of elements (#{value_class.max_num_elements})"
-        raise Error, construct_error_message(param_name, value, message)
+        raise Error, construct_error_message(param_name, raw_value, message)
       end
 
       return value
     elsif((value_class == Boolean) &&
-          ((value.class == TrueClass) || (value.class == FalseClass)))
+          ((raw_value.class == TrueClass) || (raw_value.class == FalseClass)))
       #
       # If we're looking for a Boolean, then we just can return
-      # the ConfigReader's value if it's true or false.
+      # the reader's value if it's true or false.
       #
-      return value
-    elsif(value.class == String)
+      return raw_value
+    elsif(raw_value.class == String)
       #
-      # Some ConfigReaders only may return strings and leave it up to
+      # Some readers only may return Strings and leave it up to
       # the caller to figure out the proper types for the parameters.
-      # In our case, we'll levarage Ruby's built-in conversion functions
+      # We'll levarage Ruby's built-in conversion functions
       # to support the most common parameter types.  Should this be
       # made extensible?
       #
       case
       when (value_class <= Integer)
-        return Integer(value)
+        return Integer(raw_value)
       when (value_class <= Float)
-        return Float(value)
+        return Float(raw_value)
       when (value_class <= Pathname)
-        return Pathname(value)
+        return Pathname(raw_value)
       when (value_class <= Symbol)
-        return value.to_sym()
+        return raw_value.to_sym()
       when (value_class <= URI)
-        return URI(value)
+        return URI(raw_value)
       when (value_class == Boolean)
         #
         # Support both yes/no and true/false boolean values.
         #
-        if((value.casecmp("yes") == 0) || (value.casecmp("true") == 0))
+        if((raw_value.casecmp("yes") == 0) || (raw_value.casecmp("true") == 0))
           return true
-        elsif((value.casecmp("no") == 0)|| (value.casecmp("false") == 0))
+        elsif((raw_value.casecmp("no") == 0)|| (raw_value.casecmp("false") == 0))
           return false
         end
       end
     end
 
-    message = "cannot convert from value class #{value.class.name} to specified class #{value_class.name}"
-    raise Error, construct_error_message(param_name, value, message)
+    message = "cannot convert from value class #{raw_value.class.name} to specified class #{value_class.name}"
+    raise Error, construct_error_message(param_name, raw_value, message)
   end
   private :load_value_impl
 
   # 
   # ====Description:
-  # 
+  # This method loads self from containing_object_hash, which
+  # must contain key/value pairs, where the keys are
+  # parameter names (Strings) and the values are parameter
+  # values (to be passed to load_value_impl).  The configuration's
+  # specifications are enforced by this method.
   # 
   # ====Parameters:
   # [containing_object_hash]
-  #      ?
-  # [containing_object_name]
-  #      ?
+  #      The Hash containing the configuration's parameters
   # 
-  # ====Returns:
-  # 
-  # 
-  def load_impl(containing_object_hash, containing_object_name)
-    @containing_object_name = containing_object_name
+  def load_impl(containing_object_hash)
     @params_with_values.clear()
 
     if(containing_object_hash != nil)
@@ -684,16 +757,17 @@ class BaseConfig
 
   # 
   # ====Description:
-  # 
+  # This method loads self from reader (with containing object
+  # containing_object_name).
   # 
   # ====Parameters:
   # [reader]
-  #      ?
+  #      The reader from which to load the parameter values.  This method
+  #      will call the read method of reader, which will return
+  #      a Hash containing, in the most nested containing object entry,
+  #      the configuration parameter values for self.
   # [containing_object_name = ""]
-  #      ?
-  # 
-  # ====Returns:
-  # 
+  #      The containing object name
   # 
   def load(reader, containing_object_name = "")
     param_hash = reader.read
@@ -705,11 +779,12 @@ class BaseConfig
     end
 
     #
-    # Work through the param_hash until containing_object_name is found by
+    # Work through the param_hash until the most nested object in
+    # containing_object_name is found by
     # splitting up containing_object_name into an object list and
     # hashing for each.  For example, production.webserver.tokyo would
     # result in a lookup for production, the results of which them would be
-    # searched for webserver, the results of which finally would be search
+    # searched for webserver, the results of which finally would be searched
     # for tokyo.  Not being able to find one of the objects is not
     # (necessarily) an error; that just means that none of the parameters will
     # be set from param_hash, which is allowable if all of the parameters
@@ -717,8 +792,9 @@ class BaseConfig
     # is empty).  On the other hand, if an object is found but it is not
     # really an object (a Hash), then raise an exception.
     #
+    @containing_object_name = containing_object_name
     containing_object_hash = param_hash
-    containing_object_name.split(".").each do |object_name|
+    @containing_object_name.split(".").each do |object_name|
       containing_object_hash = containing_object_hash.fetch(object_name, nil)
 
       if(containing_object_hash == nil)
@@ -727,26 +803,25 @@ class BaseConfig
         message =  "error: #{self.class}#load found "
         message << "#{containing_object_hash.class} "
         message << "rather than Hash when reading the "
-        message << "#{containing_object_name} containing object"
+        message << "#{object_name} containing object"
         raise Error, message
       end
     end
 
-    load_impl(containing_object_hash, containing_object_name)
+    load_impl(containing_object_hash)
   end
 
   # 
   # ====Description:
-  # 
+  # This class method creates a new config instance and
+  # calls load on it with the specified parameters.  This
+  # is a second "constructor" for the class.
   # 
   # ====Parameters:
-  # [reader]
-  #      ?
-  # [containing_object_name = ""]
-  #      ?
+  # See the parameter list for load.
   # 
   # ====Returns:
-  # 
+  # The new instance, preloaded!
   # 
   def self.load(reader, containing_object_name = "")
     instance = new()
@@ -756,25 +831,21 @@ class BaseConfig
   
   # 
   # ====Description:
-  # 
+  # This method writes parameter value value to str, with
+  # indentation indent.
   # 
   # ====Parameters:
   # [str]
-  #      ?
+  #      The String to which to write
   # [indent]
-  #      ?
-  # [value_class]
-  #      ?
+  #      The indentation at which to write value
   # [value]
-  #      ?
+  #      The parameter value to write
   # 
-  # ====Returns:
-  # 
-  # 
-  def write_value_impl(str, indent, value_class, value)
+  def write_value_impl(str, indent, value)
     nesting_indent = indent + NESTING_INDENT
     if(value != nil)
-      if(value_class < BaseConfig)
+      if(value.class < BaseConfig)
         #
         # Writing a nested config requires calling its write(),
         # just at one further indentation level.
@@ -782,19 +853,18 @@ class BaseConfig
         str << "{\n"
         value.write_impl(str, nesting_indent)
         str << indent << "}"
-      elsif(value_class < ConstrainedArray)
+      elsif(value.class < Array)
         #
-        # Writing an array requires going through each element and
-        # calling write_value_impl, just at one further indentation
-        # level.
+        # Writing an array requires calling write_value_impl for each element,
+        # just at one further indentation level.
         #
         str << "[\n"
 
         value.each_with_index do |element, index|
           str << nesting_indent
-          write_value_impl(str, nesting_indent, value_class.element_class, element)
+          write_value_impl(str, nesting_indent, element)
 
-          if(index != (value.length - 1))
+          if(index < (value.length - 1))
             str << ","
           end
 
@@ -811,34 +881,28 @@ class BaseConfig
 
   # 
   # ====Description:
-  # 
+  # This method writes self to str, at indentation indent.
   # 
   # ====Parameters:
   # [str]
-  #      ?
+  #      The String to which to write
   # [indent]
-  #      ?
-  # 
-  # ====Returns:
-  # 
+  #      The indentation at which to write self
   # 
   def write_impl(str, indent)
+    name_field_length = self.class.longest_param_name_length
     self.class.param_spec_list.each do |param_spec|
-      name_field_length = self.class.longest_param_name_length
       str << indent << param_spec.name.to_s.ljust(name_field_length) << ": "
       value = send(param_spec.name)
-      write_value_impl(str, indent, param_spec.value_class, value)
+      write_value_impl(str, indent, value)
       str << "\n"
     end
   end
   protected :write_impl
 
-  # 
-  # ====Description:
-  # 
   # 
   # ====Returns:
-  # 
+  # String representation of self
   # 
   def to_s
     #