Add documentation comments to code

keyth.gemspec

@@ -1,8 +1,8 @@
 # encoding: utf-8
 Gem::Specification.new do |s|
   s.name        = 'keyth'
-  s.version     = '0.2.1'
-  s.date        = '2014-08-17'
+  s.version     = '0.2.2'
+  s.date        = '2014-08-19'
   s.summary     = 'Keyth!'
   s.description = 'Handles named keys for use in config files'
   s.authors     = ['K M Lawrence']

lib/keyth.rb

@@ -6,6 +6,9 @@
 # Keyhandling module with various functions for keeping keys
 # out of configuration files.
 module Keyth
+  # Retrieves a key from the store, raising errors if the key is missing
+  # Params:
+  # +key+:: name of the key (without the keyth: prefix)
   def self.get_key(key)
     load_keyfile unless @key_list
     application, key_name = key.split('/')
@@ -14,10 +17,17 @@ def self.get_key(key)
     @key_list[application][key_name]
   end
 
+  # Retrieves a key from the store, returning nil if the key is missing
+  # Params:
+  # +key+:: name of the key (without the keyth: prefix)
   def self.get_key_safe(key)
     get_key(key) rescue nil
   end
 
+  # Adds a key to the store
+  # Params:
+  # +key+:: name of the key (without the keyth: prefix)
+  # +value+:: the key value
   def self.add_key(key, value)
     load_keyfile unless @key_list
     application, key_name = key.split('/')
@@ -26,6 +36,9 @@ def self.add_key(key, value)
     save_keyfile
   end
 
+  # Removes a key from the store
+  # Params:
+  # +key+:: name of the key (without the keyth: prefix)
   def self.delete_key(key)
     load_keyfile unless @key_list
     application, key_name = key.split('/')
@@ -34,6 +47,9 @@ def self.delete_key(key)
     save_keyfile
   end
 
+  # Gets a list of keys in the store
+  # Params:
+  # +application+:: if not nil, only return keys where the part of the key before the slash matches.
   def self.keys(application = nil)
     load_keyfile unless @key_list
     keys = {}
@@ -45,12 +61,18 @@ def self.keys(application = nil)
     keys
   end
 
+  # Reads a YAML file, automatically retrieving keys for any value prefixed with "keyth:"
+  # Params:
+  # +file+:: file object containing YAML to read
   def self.load_yaml(file)
     load_keyfile unless @key_list
     keys = YAML.pre_keyth_load(file)
     fetch_keys(keys)
   end
 
+  # Fixes a string, array-alike, or hash-alike by automatically retrieving keys for any value prefixed with "keyth:"
+  # Params:
+  # +obj+:: the object to fix
   def self.fetch_keys(obj)
     load_keyfile unless @key_list
     case
@@ -63,7 +85,7 @@ def self.fetch_keys(obj)
         obj[i] = fetch_keys(v)
       end
     when obj.is_a?(String)
-      obj = obj.gsub(/^keyth\:(.*)/) { get_key(Regexp.last_match[1]) }
+      obj = obj.gsub(/^keyth\:(.*)/) { get_key_safe(Regexp.last_match[1]) || "Missing Key: [#{obj}]" }
     end
     obj
   end
@@ -78,11 +100,8 @@ def self.namespace(namespace)
     @namespace
   end
 
-  def self.keyfile_location
-    @namespace = 'default' unless @namespace
-    ENV['KEYTH_KEYFILE'] || File.join(Dir.home, '.keyth', @namespace + '.yml')
-  end
-
+  # Load the keyfile. By default, the keystore is loaded if necessary by
+  # the using functions, so it is unnecessary to call this directly.
   def self.load_keyfile
     if File.file?(keyfile_location)
       @key_list = YAML.pre_keyth_load(File.open(keyfile_location))
@@ -91,12 +110,17 @@ def self.load_keyfile
     end
   end
 
+  # Save the keyfile. By default, the keystore is saved when changes are
+  # made to it, so it is unnecessary to call this directly.
   def self.save_keyfile
     load_keyfile unless @key_list
     File.open(keyfile_location, 'w') { |f| f.write @key_list.to_yaml }
   end
-end
-
-
 
+  private
 
+  def self.keyfile_location
+    @namespace = 'default' unless @namespace
+    ENV['KEYTH_KEYFILE'] || File.join(Dir.home, '.keyth', @namespace + '.yml')
+  end
+end

lib/keyth/dotenv.rb

@@ -3,6 +3,8 @@
 module Dotenv
   # The two apply functions are all that need to be overwritten
   class Environment
+    # sets all environment variables that are keyth: links with the
+    # appropriate key value, sets all missing env variables otherwise
     def apply
       each do |k, v|
         if v =~ /^keyth\:(.*)/
@@ -13,7 +15,10 @@ def apply
       end
     end
 
-    def apply
+    # sets all environment variables that are keyth: links with the
+    # appropriate key value, overwrites all env variables with the
+    # contents from .env otherwise
+    def apply!
       each do |k, v|
         if v =~ /^keyth\:(.*)/
           ENV[k] = Keyth.get_key_safe(Regexp.last_match[1]) || ''

lib/keyth/yaml.rb

@@ -5,7 +5,11 @@ class << self
     alias_method(:pre_keyth_load, :load)
   end
 
+  # loads the yaml file, then replaces all keyth: links with the
+  # appropriate values.
+  # Params:
+  # +file+:: file object containing YAML to read
   def self.load(file)
     Keyth.fetch_keys(pre_keyth_load(file))
   end
-end
+end