From 0f5b2b764a7d0186fe842ecf18f4d9fb0241a673 Mon Sep 17 00:00:00 2001
From: Michael Kessler <michi@netzpiraten.ch>
Date: Tue, 20 Sep 2011 12:07:34 +0200
Subject: [PATCH] Initial yardoc for the main Guard class for specific
 implementations.

---
 lib/guard/guard.rb | 54 +++++++++++++++++++++++++++++++++++-----------
 1 file changed, 42 insertions(+), 12 deletions(-)

diff --git a/lib/guard/guard.rb b/lib/guard/guard.rb
index acd4ddd..e6c911f 100644
--- a/lib/guard/guard.rb
+++ b/lib/guard/guard.rb
@@ -1,21 +1,39 @@
 module Guard
+
+  # Main class that every Guard implementation must subclass.
+  #
+  # Guard will trigger the `start`, `stop`, `reload`, `run_all` and `run_on_change`
+  # methods depending on user interaction and file modification.
+  #
+  # Each Guard should provide a template Guardfile located within the Gem
+  # at `lib/guard/guard-name/templates/Guardfile`.
+  #
   class Guard
     include Hook
 
     attr_accessor :watchers, :options, :group
 
+    # initialize a Guard.
+    #
+    # @param [Array<Guard::Watcher>] watchers the Guard file watchers
+    # @param [Hash] options the custom Guard options.
+    #
     def initialize(watchers = [], options = {})
       @group = options.delete(:group) || :default
       @watchers, @options = watchers, options
     end
 
-    # Guardfile template needed inside guard gem
+    # Initialize the Guard. This will copy the Guardfile template inside the Guard gem.
+    # The template Guardfile must be located within the Gem at `lib/guard/guard-name/templates/Guardfile`.
+    #
+    # @param [String] name the name of the Guard
+    #
     def self.init(name)
       if ::Guard::Dsl.guardfile_include?(name)
-        ::Guard::UI.info "Guardfile already includes #{name} guard"
+        ::Guard::UI.info "Guardfile already includes #{ name } guard"
       else
         content = File.read('Guardfile')
-        guard   = File.read("#{::Guard.locate_guard(name)}/lib/guard/#{name}/templates/Guardfile")
+        guard   = File.read("#{ ::Guard.locate_guard(name) }/lib/guard/#{ name }/templates/Guardfile")
         File.open('Guardfile', 'wb') do |f|
           f.puts(content)
           f.puts("")
@@ -25,31 +43,43 @@ module Guard
       end
     end
 
-    # ================
-    # = Guard method =
-    # ================
-
-    # Call once when guard starts
-    # Please override initialize method to init stuff
+    # Call once when guard starts. Please override initialize method to init stuff.
+    #
+    # @return [Boolean] Whether the start action was successful or not
+    #
     def start
       true
     end
 
-    # Call once when guard quit
+    # Call once when guard quit.
+    #
+    # @return [Boolean] Whether the stop action was successful or not
+    #
     def stop
       true
     end
 
-    # Should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
+    # Should be used for "reload" (really!) actions like reloading passenger/spork/bundler/...
+    #
+    # @return [Boolean] Whether the reload action was successful or not
+    #
     def reload
       true
     end
 
-    # Should be principally used for long action like running all specs/tests/...
+    # Should be  used for long action like running all specs/tests/...
+    #
+    # @return [Boolean] Whether the run_all action was successful or not
+    #
     def run_all
       true
     end
 
+    # Will be triggered when a file change matched a watcher.
+    #
+    # @param [Array<String>] paths the changes files or paths
+    # @return [Boolean] Whether the run_all action was successful or not
+    #
     def run_on_change(paths)
       true
     end