From dc009d445a1a4356d366be80632beb34bff40e34 Mon Sep 17 00:00:00 2001
From: Michael Kessler <michi@netzpiraten.ch>
Date: Tue, 20 Sep 2011 11:49:05 +0200
Subject: [PATCH] Add yardoc for the DslDescriber.

---
 lib/guard/dsl.rb           | 10 +++++++---
 lib/guard/dsl_describer.rb | 40 ++++++++++++++++++++++++++++++++++----
 2 files changed, 43 insertions(+), 7 deletions(-)

diff --git a/lib/guard/dsl.rb b/lib/guard/dsl.rb
index 66427c6..0f572b9 100644
--- a/lib/guard/dsl.rb
+++ b/lib/guard/dsl.rb
@@ -250,7 +250,7 @@ module Guard
 
     end
 
-    # Declares a group of guards to be run with `guard start --group group_name`
+    # Declares a group of guards to be run with `guard start --group group_name`.
     #
     # @example Declare two groups of Guards
     #   group 'backend' do
@@ -267,14 +267,17 @@ module Guard
     # @yield a block where you can declare several guards
     #
     # @see Dsl#guard
+    # @see Guard::DslDescriber
     #
-    def group(name, &guard_definition)
+    def group(name)
       @groups = @@options[:group] || []
       name    = name.to_sym
 
       if guard_definition && (@groups.empty? || @groups.map(&:to_sym).include?(name))
         @current_group = name
-        guard_definition.call
+
+        yield if block_given?
+
         @current_group = nil
       end
     end
@@ -295,6 +298,7 @@ module Guard
     # @yield a block where you can declare several watch patterns and actions
     #
     # @see Dsl#watch
+    # @see Guard::DslDescriber
     #
     def guard(name, options = {})
       @watchers  = []
diff --git a/lib/guard/dsl_describer.rb b/lib/guard/dsl_describer.rb
index b9908ff..be2446e 100644
--- a/lib/guard/dsl_describer.rb
+++ b/lib/guard/dsl_describer.rb
@@ -1,28 +1,60 @@
 require 'guard/dsl'
 
 module Guard
+
+  # The DslDescriber overrides methods to create an internal structure
+  # of the Guardfile that is used in some inspection utility methods
+  # like the CLI commands `show` and `list`.
+  #
+  # @see Guard::DSL
+  # @see Guard::CLI
+  #
   class DslDescriber < Dsl
+
     @@guardfile_structure = [ { :guards => [] } ]
 
     class << self
+
+      # Get the Guardfile structure.
+      #
+      # @return [Array<Hash>] the structure
+      #
       def guardfile_structure
         @@guardfile_structure
       end
     end
 
     private
-    def group(name, &guard_definition)
-      @@guardfile_structure << { :group => name.to_sym, :guards => [] }
 
+    # Declares a group of guards.
+    #
+    # @param [String] name the group's name called from the CLI
+    # @yield a block where you can declare several guards
+    #
+    # @see Guard::Dsl
+    #
+    def group(name)
+      @@guardfile_structure << { :group => name.to_sym, :guards => [] }
       @group = true
-      guard_definition.call
+
+      yield if block_given?
+
       @group = false
     end
 
-    def guard(name, options = {}, &watch_definition)
+    # Declare a guard.
+    #
+    # @param [String] name the Guard name
+    # @param [Hash] options the options accepted by the Guard
+    # @yield a block where you can declare several watch patterns and actions
+    #
+    # @see Guard::Dsl
+    #
+    def guard(name, options = {})
       node = (@group ? @@guardfile_structure.last : @@guardfile_structure.first)
 
       node[:guards] << { :name => name, :options => options }
     end
+
   end
 end