Document the source, using 'Yard' syntax.

Code now passes 'inch --pedantic' with no errors.

Signed-off-by: Seapagan <seapagan@gmail.com>

lib/confoog.rb

@@ -4,27 +4,41 @@
 # Overall module.
 # Contains Class Confoog::Settings
 module Confoog
+  # The default filename used if none specified when created.
   DEFAULT_CONFIG = '.confoog'
 
   # Error messages to be returned
+
+  # No error condition exists
   ERR_NO_ERROR = 0
+  # The specified file does not exist
   ERR_FILE_NOT_EXIST = 1
+  # You cannot change location or filename after class is instantiated
   ERR_CANT_CHANGE = 2
+  # Was unable to create the specified file
   ERR_CANT_CREATE_FILE = 4
+  # There are no configuration variables set, so not writing empty file
   ERR_NOT_WRITING_EMPTY_FILE = 8
+  # Cannot save to the specified file for some reason
   ERR_CANT_SAVE_CONFIGURATION = 16
+  # The specified file is empty so not trying to load settings from it
   ERR_NOT_LOADING_EMPTY_FILE = 32
 
   # Info messages to be returned
+
+  # Information - file was created successfully
   INFO_FILE_CREATED = 256
+  # Information - configuration was successfully loaded
   INFO_FILE_LOADED = 512
 
+  # Hash containing text versions of the assorted error severity.
   OUTPUT_SEVERITY = {
     ERR: 'Error',
     WARN: 'Warning',
     INFO: 'Information'
   }
 
+  # Hash containing default values of initialization variables
   DEFAULT_OPTIONS = {
     create_file: false,
     quiet: false,
@@ -33,21 +47,54 @@ module Confoog
     filename: DEFAULT_CONFIG
   }
 
+  # rubocop:disable LineLength
   # Class : Settings.
   # Provide an encapsulated class to access a YAML configuration file.
-  # Readers :
-  # .filename = read the config filename for this instance
-  # .location = read the config directory for this instance
-  # .status = Hash containing assorted status variables, read only.
+  # @!attribute [r] filename
+  #   @return [String] The configuration filename in use.
+  # @!attribute [r] location
+  #   @return [String] The directory storing the configuration file.
+  # @!attribute [r] status
+  #   @return [Hash] A hash containing status variables.
+  # @example
+  #   require 'confoog'
+  #   settings = Confoog::Settings.new
+  #   settings[:var] = value
+  #   settings[:array] = [1, 2, 3, 4]
+  #   settings[42] = "Meaning of life"
+  #   settings[:urls] = ["https://www.mywebsite.com", "https://www.anothersite.com/a/page.html"]
+  #
+  #   settings[:urls].each do |url|
+  #     puts url
+  #   end
+  #   # https://www.mywebsite.com
+  #   # https://www.anothersite.com/a/page.html
+  #   # => ["https://www.mywebsite.com", "https://www.anothersite.com/a/page.html"]
+  #
+  #   settings[:dont_exist]
+  #   # => nil
+  #
+  #   a_variable = 50
+  #   settings[a_variable] = {:one => "for the money", :two => "for the show", :three => "to get ready"}
+  #   settings[50]
+  #   # => {:one => "for the money", :two => "for the show", :three => "to get ready"}
+  #   settings[50][:two]
+  #   # => "for the show"
+  # rubocop:enable LineLength
   class Settings
     attr_reader :filename, :location, :status
 
+    # Setup the class with specified parameters or default values if any or all
+    # are absent.
+    # All parameters are optional.
+    # @param options [Hash] Hash value containing any passed parameters.
     def initialize(options = {})
       # merge default options to avoid ambiguity
       @options = DEFAULT_OPTIONS.merge(options)
       # set all other unset options to return false instead of Nul.
       @options.default = false
 
+      # Hash containing any error or return from methods
       @status = {}
       @location = @options[:location]
       @filename = @options[:filename]
@@ -60,14 +107,29 @@ def initialize(options = {})
       check_exists(options)
     end
 
+    # Return the value of the 'quiet' option.
+    # @example
+    #   is_quiet = settings.quiet
+    # @param [None]
+    # @return [Boolean] True if we are not writing to the console on error
     def quiet
       @options[:quiet]
     end
 
+    # Change the 'quiet' option.
+    # @example
+    #   settings.quiet = true
+    # @return [Boolean] The new value [true | false]
+    # @param quiet [Boolean] True to send messages to console for errors.
     def quiet=(quiet)
       @options[:quiet] = quiet
     end
 
+    # Save the entire configuration (@config) to the YAML file.
+    # @example
+    #   settings.save
+    # @param [None]
+    # @return Unspecified
     def save
       if @config.count > 0
         save_to_yaml
@@ -78,6 +140,11 @@ def save
       end
     end
 
+    # Populate the configuration (@config) from the YAML file.
+    # @param [None]
+    # @example
+    #   settings.load
+    # @return Unspecified
     def load
       @config = YAML.load_file(config_path)
       status_set(errors: INFO_FILE_LOADED)
@@ -91,32 +158,45 @@ def load
                      OUTPUT_SEVERITY[:ERR])
     end
 
+    # dummy method currently to stop changing location by caller once created,
+    # @return [hash] an error flag in the ':status' variable.
+    # @param [Optional] Parameter is ignored
     def location=(*)
-      # dummy method currently to stop changing location by caller once created,
-      # but not raise error.
-      #  - Return an error flag in the ':status' variable.
       status_set(errors: ERR_CANT_CHANGE)
       console_output('Cannot change file location after creation',
                      OUTPUT_SEVERITY[:WARN])
     end
 
+    # dummy method currently to stop changing filename by caller once created,
+    # @return [hash] an error flag in the ':status' variable.
+    # @param optional Parameter is ignored
     def filename=(*)
-      # dummy method currently to stop changing filename by caller once created,
-      # but not raise error.
-      #  - Return an error flag in the ':status' variable.
       status_set(errors: ERR_CANT_CHANGE)
       console_output('Cannot change filename after creation',
                      OUTPUT_SEVERITY[:WARN])
     end
 
+    # Read the configuration key (key)
+    # @example
+    #   key = settings[:key]
+    # @return [<various>] Return value depends on the type of variable stored
     def [](key)
       @config[key]
     end
 
+    # Set a configuration key
+    # @example
+    #   settings[:key] = "Value"
+    #   settings[:array] = ["first", "second", "third"]
+    # @return [<various>] Returns the variable that was assigned.
     def []=(key, value)
       @config[key] = value
     end
 
+    # Returns the fully qualified path to the configuration file in use.
+    # @example
+    #   path = getpath
+    # @return [String] Full path and filename of the configuration file.
     def config_path
       File.expand_path(File.join(@location, @filename))
     end

lib/confoog/version.rb

@@ -1,4 +1,6 @@
 # Define the Gem version string
 module Confoog
+  # Version of this Gem, using Semantic Versioning 2.0.0
+  # http://semver.org/
   VERSION = '0.1.4'
 end