From 5bdb56caa0bdc540b08f0115ffc3a96a1855740b Mon Sep 17 00:00:00 2001 From: Michael Kessler Date: Fri, 30 Sep 2011 11:30:05 +0200 Subject: [PATCH] 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 | 45 ++++++++++++++++++--------------------- lib/guard.rb | 3 ++- lib/guard/group.rb | 17 ++++++++++++++- lib/guard/guard.rb | 53 +++++++++++++++++++++++++++++----------------- 4 files changed, 73 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index c612566..a231795 100644 --- a/README.md +++ b/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] watchers the Guard file watchers + # @param [Hash] options the custom Guard options def initialize(watchers = [], options = {}) super - # init stuff here, thx! end - # ================= - # = Guard methods = - # ================= - - # 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 + # Call once when Guard starts. Please override initialize method to init stuff. + # @raise [:task_has_failed] when start has failed 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] 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] 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 diff --git a/lib/guard.rb b/lib/guard.rb index b41b0ec..2367f93 100644 --- a/lib/guard.rb +++ b/lib/guard.rb @@ -218,6 +218,7 @@ module Guard # @param [Array] 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) diff --git a/lib/guard/group.rb b/lib/guard/group.rb index c8239b1..a723bf5 100644 --- a/lib/guard/group.rb +++ b/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` # diff --git a/lib/guard/guard.rb b/lib/guard/guard.rb index 3d59ec7..ea54c4f 100644 --- a/lib/guard/guard.rb +++ b/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` - # methods depending on user interaction and file modification. + # Guard will trigger the `start`, `stop`, `reload`, `run_all`, `run_on_change` and + # `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] 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] 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