From 22afc7c5262f1fc3a6811e472fc9de44d3f78cf5 Mon Sep 17 00:00:00 2001
From: Josep Jaume <josepjaume@gmail.com>
Date: Fri, 14 Oct 2011 19:09:10 +0200
Subject: [PATCH] Update features

---
 Gemfile                                       |  1 +
 Guardfile                                     |  7 ++++++
 ...e => automatic_feature_generation.feature} |  0
 lib/spinach/hookable.rb                       | 24 +++++++++++++++++--
 lib/spinach/hooks.rb                          | 23 +++---------------
 test/spinach/hookable_test.rb                 |  1 -
 6 files changed, 33 insertions(+), 23 deletions(-)
 rename features/{generate_features.feature => automatic_feature_generation.feature} (100%)

diff --git a/Gemfile b/Gemfile
index 8a6adf13..23b10e3d 100644
--- a/Gemfile
+++ b/Gemfile
@@ -6,6 +6,7 @@ gemspec
 group :test do
   gem 'guard'
   gem 'guard-minitest'
+  gem 'guard-spinach'
 end
 
 group :darwin do
diff --git a/Guardfile b/Guardfile
index 3c7ac71e..ada86c40 100644
--- a/Guardfile
+++ b/Guardfile
@@ -3,3 +3,10 @@ guard 'minitest' do
   watch(%r|^lib/(.*)([^/]+)\.rb|)     { |m| "test/#{m[1]}#{m[2]}_test.rb" }
   watch(%r|^test/test_helper\.rb|)    { "test" }
 end
+
+guard 'spinach' do
+  watch(%r|^features/(.*)\.feature|)
+  watch(%r|^features/steps/(.*)([^/]+)\.rb|) do |m|
+    "features/#{m[1]}#{m[2]}.feature"
+  end
+end
diff --git a/features/generate_features.feature b/features/automatic_feature_generation.feature
similarity index 100%
rename from features/generate_features.feature
rename to features/automatic_feature_generation.feature
diff --git a/lib/spinach/hookable.rb b/lib/spinach/hookable.rb
index 85c1e445..e34cf1ea 100644
--- a/lib/spinach/hookable.rb
+++ b/lib/spinach/hookable.rb
@@ -1,4 +1,10 @@
 module Spinach
+  # The hookable module includes subscription capabilities to the class in which
+  # it is included.
+  #
+  # Take in account that while most subscription/notification mechanism work
+  # at the class level, Hookable defines hooks at the instance level - so they
+  # are not the same in all the class instances.
   module Hookable
 
     def self.included(base)
@@ -27,6 +33,9 @@ def hook(hook)
     module InstanceMethods
       attr_writer :hooks
 
+      # @return [Hash]
+      #   hash in which the key is the hook name and the value an array of any
+      #   defined callbacks, or nil.
       def hooks
         @hooks ||= {}
       end
@@ -36,22 +45,33 @@ def reset
         self.hooks = {}
       end
 
-      # Runs a particular hook
+      # Runs a particular hook given a set of arguments
       #
       # @param [String] name
       #   the hook's name
       #
-      # @param [
       def run_hook(name, *args)
         if callbacks = hooks[name.to_sym]
           callbacks.each{ |c| c.call(*args) }
         end
       end
 
+      # @param [String] name
+      #   the hook's identifier
+      #
+      # @return [Array]
+      #   array of hooks for that particular identifier
       def hooks_for(name)
         hooks[name.to_sym] || []
       end
 
+      # Adds a hook to the queue
+      #
+      # @param [String] name
+      #   the hook's identifier
+      #
+      # @param [Proc] block
+      #   an action to perform once that hook is executed
       def add_hook(name, &block)
         hooks[name.to_sym] ||= []
         hooks[name.to_sym] << block
diff --git a/lib/spinach/hooks.rb b/lib/spinach/hooks.rb
index 59db801e..c7ab905b 100644
--- a/lib/spinach/hooks.rb
+++ b/lib/spinach/hooks.rb
@@ -1,24 +1,9 @@
 require_relative 'hookable'
 
 module Spinach
-  # The hooks class is a subscription/notification mechanism that allows you to
-  # hook into signals provided by the runner and perform certain actions on
-  # it.
-  #
-  # @example
-  #   Spinach.hooks.before_run do
-  #     # Runs before the entire spinach execution
-  #   end
-  #
-  #   Spinach.hooks.before_scenario do |scenario_data|
-  #     # Runs before every scenario and passes a hash of the parsed scenario
-  #     # data to the block as argument
-  #   end
-  #
-  #   Spinach.hooks.on_failed_step do |step_data|
-  #     # Runs before every failed stepand passes a hash of the parsed step
-  #     # data to the block as argument
-  #   end
+  # Spinach's hooks is a subscription mechanism to allow developers to define
+  # certain callbacks given several Spinach signals, like running a feature,
+  # executing a particular step and such.
   class Hooks
     include Hookable
 
@@ -143,7 +128,5 @@ class Hooks
     #     # step_data contains a hash with this step's data
     #   end
     hook :on_skipped_step
-
   end
-
 end
diff --git a/test/spinach/hookable_test.rb b/test/spinach/hookable_test.rb
index 9db5b698..4af3d2cf 100644
--- a/test/spinach/hookable_test.rb
+++ b/test/spinach/hookable_test.rb
@@ -56,5 +56,4 @@
       end
     end
   end
-
 end