updated README

README.md

@@ -3,30 +3,33 @@
 Using a yaml file and then loading it into a hash, to store settings is a common pattern.
 Over time the settings usually change, which will cause the code to contain checks for which version of the settings is used.
 
-Returns a new hash
-```
-migrated_hash = Hash::Migrator.run(hash, dir, options)
-```
+This gem introduces migrations for hashes so you can keep the code simple and maintain changes to the hash in separate migration files.
+
+It can be used in two ways, either it returns a new hash:
+
+    migrated_hash = Hash::Migrator.run(hash, dir, options)
+
+
+Or it can modify the existing hash, if you call the instance method.
+
+    hash.migrate(dir, options)
 
-Modifies the existing hash
-```
-hash.migrate(dir, options)
-```
 
 A sample hash migration looks like this, and the file should be named `YYYYMMDDHHmmss_description.rb`
-```
-Hash.migration do
-  up do |hash|
-    hash[:foo] = hash['foo']
-    hash.delete('foo')
-  end
-
-  down do
-    hash['foo'] = hash[:foo]
-    hash.delete(:foo)
-  end
-end
-```
+
+    Hash.migration do
+      up do |hash|
+        hash[:foo] = hash['foo']
+        hash.delete('foo')
+      end
+
+      down do
+        hash['foo'] = hash[:foo]
+        hash.delete(:foo)
+      end
+    end
+
+The migration assumes you have a top-level hash key named `:schema_version` (initialized to `0` if not present) which is used to track the migrations needed.
 
 ## Installation
 
@@ -42,10 +45,6 @@ Or install it yourself as:
 
     $ gem install hash-migrations
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Contributing
 
 1. Fork it

hash-migrations.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |gem|
   gem.version       = Hash::Migrations::VERSION
   gem.authors       = ["Martin Englund"]
   gem.email         = ["martin@englund.nu"]
-  gem.description   = %q{TODO: Write a gem description}
-  gem.summary       = %q{TODO: Write a gem summary}
+  gem.description   = %q{Migrations to manage hashes}
+  gem.summary       = %q{Migrations for hashes}
   gem.homepage      = ""
 
   gem.files         = `git ls-files`.split($/)

lib/hash/migrations.rb

@@ -5,8 +5,12 @@
 require 'hash/migrations/core_ext'
 
 module Hash::Migrations
-  # returns a new hash with migrations run
-  def run(hash, dir, options={direction: :up})
+  # Apply migrations to a hash
+  # @param [Hash] hash hash to be migrated
+  # @param [String] dir path to the directory containing the migrations to apply
+  # @param [Hash] options options
+  # @return [Hash] migrated hash
+def run(hash, dir, options={direction: :up})
     hash.dup.migrate(dir, options)
   end
 

lib/hash/migrations/core_ext.rb

@@ -1,4 +1,7 @@
 module Hash::Migrations::InstanceMethods
+  # Apply migrations to the hash
+  # @param [String] dir path to the directory containing the migrations to apply
+  # @param [Hash] options options
   def migrate(dir, options={})
     @direction = options.fetch(:direction, :up)
     Hash::Migrations::Migrator.new(dir).run(self, options)

lib/hash/migrations/migrator.rb

@@ -1,5 +1,6 @@
 module Hash::Migrations
   class Migrator
+    # @return [Array[Hash::Migrations::Migration]] the list of migrations in this migration
     attr_reader :migrations
 
     def initialize(migrations_dir=nil)
@@ -25,6 +26,9 @@ def add(migration)
       @migrations << migration
     end
 
+    # @param [Hash] hash hash to be migrated
+    # @param [Hash] options options
+    # @return [Hash] migrated hash
     def run(hash, options={})
       # TODO raise error on existing version format?
       # TODO only migrate to a certain version