Update docs regarding :task_has_failed.

- Add :task_has_failed documentation to Guard and Group classes
- Consolidated Guard documentation from the README and its YARDOC.
- Remove all return `true` values from Guard task methods.

README.md

@@ -328,7 +328,9 @@ Creating a new guard is very easy, just create a new gem (`bundle gem` if you us
     test/ # or spec/
     README.md
 
-`Guard::GuardName` (in `lib/guard/guard-name.rb`) must inherit from `Guard::Guard` and should overwrite at least one of the five basic `Guard::Guard` instance methods.
+`Guard::GuardName` (in `lib/guard/guard-name.rb`) must inherit from
+[Guard::Guard](http://rubydoc.info/github/guard/guard/master/Guard/Guard) and should overwrite at least one of
+the basic `Guard::Guard` task methods.
 
 Here is an example scaffold for `lib/guard/guard-name.rb`:
 
@@ -338,55 +340,52 @@ Here is an example scaffold for `lib/guard/guard-name.rb`:
     module Guard
       class GuardName < Guard
 
+        # Initialize a Guard.
+        # @param [Array<Guard::Watcher>] watchers the Guard file watchers
+        # @param [Hash] options the custom Guard options
         def initialize(watchers = [], options = {})
           super
-          # init stuff here, thx!
         end
 
-        # =================
+        # Call once when Guard starts. Please override initialize method to init stuff.
-        # = Guard methods =
+        # @raise [:task_has_failed] when start has failed
-        # =================
-
-        # If one of those methods raise an exception, the Guard::GuardName instance
-        # will be removed from the active guards.
-
-        # Called once when Guard starts
-        # Please override initialize method to init stuff
         def start
-          true
         end
 
-        # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits)
+        # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
+        # @raise [:task_has_failed] when stop has failed
         def stop
-          true
         end
 
-        # Called when `reload|r|z + enter` is pressed
+        # Called when `reload|r|z + enter` is pressed.
         # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
+        # @raise [:task_has_failed] when reload has failed
         def reload
-          true
         end
 
         # Called when just `enter` is pressed
         # This method should be principally used for long action like running all specs/tests/...
+        # @raise [:task_has_failed] when run_all has failed
         def run_all
-          true
         end
 
-        # Called on file(s) modifications
+        # Called on file(s) modifications that the Guard watches.
+        # @param [Array<String>] paths the changes files or paths
+        # @raise [:task_has_failed] when run_on_change has failed
         def run_on_change(paths)
-          true
         end
 
-        # Called on file(s) deletions
+        # Called on file(s) deletions that the Guard watches.
+        # @param [Array<String>] paths the deleted files or paths
+        # @raise [:task_has_failed] when run_on_change has failed
         def run_on_deletion(paths)
-          true
         end
 
       end
     end
 
-Please take a look at the [existing guards' source code](https://github.com/guard/guard/wiki/List-of-available-Guards) for more concrete example and inspiration.
+Please take a look at the [existing guards' source code](https://github.com/guard/guard/wiki/List-of-available-Guards)
+for more concrete example and inspiration.
 
 Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
 
@@ -395,11 +394,9 @@ Alternatively, a new guard can be added inline to a Guardfile with this basic st
     module ::Guard
       class InlineGuard < ::Guard::Guard
         def run_all
-          true
         end
 
         def run_on_change(paths)
-          true
         end
       end
     end

lib/guard.rb

@@ -218,6 +218,7 @@ module Guard
     # @param [Array<String>] files the list of files to pass to the task
     # @param [Guard::Guard] guard the guard to run
     # @param [Symbol] task the task to run
+    # @raise [:task_has_failed] when task has failed
     #
     def run_on_change_task(files, guard, task)
       paths = Watcher.match_files(guard, files)
@@ -264,7 +265,7 @@ module Guard
     # @param [Guard::Guard] guard the Guard to execute
     # @param [Symbol] task the task to run
     # @param [Array] args the arguments for the task
-    # @return [Boolean, Exception] the result of the Guard
+    # @raise [:task_has_failed] when task has failed
     #
     def run_supervised_task(guard, task, *args)
       guard.hook("#{ task }_begin", *args)

lib/guard/group.rb

@@ -1,6 +1,20 @@
 module Guard
 
-  # A group of Guards.
+  # A group of Guards. There are two reasons why you want to group your guards:
+  #
+  # - You can start only certain Groups from the command line by passing the `--group` option.
+  # - Abort task execution chain on failure within a group.
+  #
+  # @example Group that aborts on failure
+  #
+  #   group :frontend, :halt_on_fail => true do
+  #     guard 'coffeescript', :input => 'spec/coffeescripts', :output => 'spec/javascripts'
+  #     guard 'jasmine-headless-webkit' do
+  #       watch(%r{^spec/javascripts/(.*)\..*}) { |m| newest_js_file("spec/javascripts/#{m[1]}_spec") }
+  #     end
+  #   end
+  #
+  # @see Guard::CLI
   #
   class Group
 
@@ -9,6 +23,7 @@ module Guard
     # Initialize a Group.
     #
     # @param [String] name the name of the group
+    # @param [Hash] options the group options
     # @option options [Boolean] halt_on_fail if a task execution
     #   should be halted for all Guards in this group if one Guard throws `:task_has_failed`
     #

lib/guard/guard.rb

@@ -2,12 +2,31 @@ module Guard
 
   # Main class that every Guard implementation must subclass.
   #
-  # Guard will trigger the `start`, `stop`, `reload`, `run_all` and `run_on_change`
+  # Guard will trigger the `start`, `stop`, `reload`, `run_all`, `run_on_change` and
-  # methods depending on user interaction and file modification.
+  # `run_on_deletion` methods depending on user interaction and file modification.
+  #
+  # In each of these Guard methods you have to implement some work when you want to
+  # support this kind of task. The return value of each Guard method is ignored, but
+  # you can raise a `:task_has_failed` exception to indicate that your Guard method was
+  # not successful. When a `:task_has_failed` exception is raised, successive guard tasks
+  # can be aborted when the group has set the `:halt_on_fail` option.
+  #
+  # @see Guard::Group
+  #
+  # @example Raise a :task_has_failed exception
+  #
+  #   def run_all
+  #     if !runner.run(['all'])
+  #       raise :task_has_failed
+  #     end
+  #   end
   #
   # Each Guard should provide a template Guardfile located within the Gem
   # at `lib/guard/guard-name/templates/Guardfile`.
   #
+  # If one of those methods raise an exception other than `:task_has_failed`,
+  # the Guard::GuardName instance will be removed from the active guards.
+  #
   class Guard
     include Hook
 
@@ -45,52 +64,48 @@ module Guard
 
     # Call once when Guard starts. Please override initialize method to init stuff.
     #
-    # @return [Boolean] Whether the start action was successful or not
+    # @raise [:task_has_failed] when start has failed
     #
     def start
-      true
     end
 
-    # Call once when Guard quit.
+    # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
     #
-    # @return [Boolean] Whether the stop action was successful or not
+    # @raise [:task_has_failed] when stop has failed
     #
     def stop
-      true
     end
 
-    # Should be used for "reload" (really!) actions like reloading passenger/spork/bundler/...
+    # Called when `reload|r|z + enter` is pressed.
+    # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
     #
-    # @return [Boolean] Whether the reload action was successful or not
+    # @raise [:task_has_failed] when reload has failed
     #
     def reload
-      true
     end
 
-    # Should be used for long action like running all specs/tests/...
+    # Called when just `enter` is pressed
+    # This method should be principally used for long action like running all specs/tests/...
     #
-    # @return [Boolean] Whether the run_all action was successful or not
+    # @raise [:task_has_failed] when run_all has failed
     #
     def run_all
-      true
     end
 
-    # Will be triggered when a file change matched a watcher.
+    # Called on file(s) modifications that the Guard watches.
     #
     # @param [Array<String>] paths the changes files or paths
-    # @return [Boolean] Whether the run_on_change action was successful or not
+    # @raise [:task_has_failed] when run_on_change has failed
     #
     def run_on_change(paths)
-      true
     end
 
-    # Will be triggered when a file deletion matched a watcher.
+    # Called on file(s) deletions that the Guard watches.
     #
     # @param [Array<String>] paths the deleted files or paths
-    # @return [Boolean] Whether the run_on_deletion action was successful or not
+    # @raise [:task_has_failed] when run_on_change has failed
     #
     def run_on_deletion(paths)
-      true
     end
 
   end