Initial yardoc for Guard.

lib/guard.rb

@@ -12,7 +12,16 @@ module Guard
   class << self
     attr_accessor :options, :guards, :groups, :interactor, :listener
 
-    # initialize this singleton
+    # Initialize the Guard singleton.
+    #
+    # @param [Hash] options the Guard options.
+    # @option options [Boolean] clear if auto clear the UI should be done
+    # @option options [Boolean] notify if system notifications should be shown
+    # @option options [Boolean] debug if debug output should be shown
+    # @option options [Array<String>] group the list of groups to start
+    # @option options [String] watchdir the director to watch
+    # @option options [String] guardfile the path to the Guardfile
+    #
     def setup(options = {})
       @options    = options
       @guards     = []
@@ -20,7 +29,7 @@ module Guard
       @interactor = Interactor.new
       @listener   = Listener.select_and_init(@options[:watchdir] ? File.expand_path(@options[:watchdir]) : Dir.pwd)
 
-      @options[:notify] && ENV["GUARD_NOTIFY"] != 'false' ? Notifier.turn_on : Notifier.turn_off
+      @options[:notify] && ENV['GUARD_NOTIFY'] != 'false' ? Notifier.turn_on : Notifier.turn_off
 
       UI.clear if @options[:clear]
       debug_command_execution if @options[:debug]
@@ -28,6 +37,17 @@ module Guard
       self
     end
 
+    # Start Guard by evaluate the `Guardfile`, initialize the declared Guards
+    # and start the available file change listener.
+    #
+    # @param [Hash] options the Guard options.
+    # @option options [Boolean] clear if auto clear the UI should be done
+    # @option options [Boolean] notify if system notifications should be shown
+    # @option options [Boolean] debug if debug output should be shown
+    # @option options [Array<String>] group the list of groups to start
+    # @option options [String] watchdir the director to watch
+    # @option options [String] guardfile the path to the Guardfile
+    #
     def start(options = {})
       setup(options)
 
@@ -45,36 +65,46 @@ module Guard
       listener.start
     end
 
+    # Stop Guard listening to file changes
+    #
     def stop
-      UI.info "Bye bye...", :reset => true
+      UI.info 'Bye bye...', :reset => true
       listener.stop
       guards.each { |guard| supervised_task(guard, :stop) }
       abort
     end
 
+    # Reload all Guards currently enabled.
+    #
     def reload
       run do
         guards.each { |guard| supervised_task(guard, :reload) }
       end
     end
 
+    # Trigger `run_all` on all Guards currently enabled.
+    #
     def run_all
       run do
         guards.each { |guard| supervised_task(guard, :run_all) }
       end
     end
 
+    # Pause Guard listening to file changes.
+    #
     def pause
       if listener.locked
-        UI.info "Un-paused files modification listening", :reset => true
+        UI.info 'Un-paused files modification listening', :reset => true
         listener.clear_changed_files
         listener.unlock
       else
-        UI.info "Paused files modification listening", :reset => true
+        UI.info 'Paused files modification listening', :reset => true
         listener.lock
       end
     end
 
+    # Trigger `run_on_change` on all Guards currently enabled and
+    #
     def run_on_change(files)
       run do
         guards.each do |guard|
@@ -87,6 +117,11 @@ module Guard
       end
     end
 
+    # Run a block where the listener and the interactor is
+    # blocked.
+    #
+    # @yield the block to run
+    #
     def run
       listener.lock
       interactor.lock
@@ -99,24 +134,40 @@ module Guard
       listener.unlock
     end
 
-    # Let a guard execute its task but
+    # Let a Guard execute its task, but fire it
-    # fire it if his work leads to a system failure
+    # if his work leads to a system failure.
+    #
+    # @param [Guard::Guard] the guard to execute
+    # @param [Symbol] task_to_supervise the task to run
+    # @params [Array] args the arguments for the task
+    # @return [Boolean, Exception] the result of the Guard
+    #
     def supervised_task(guard, task_to_supervise, *args)
       guard.hook("#{ task_to_supervise }_begin", *args)
       result = guard.send(task_to_supervise, *args)
       guard.hook("#{ task_to_supervise }_end", result)
+
       result
+
     rescue Exception => ex
       UI.error("#{ guard.class.name } failed to achieve its <#{ task_to_supervise.to_s }>, exception was:" +
                "\n#{ ex.class }: #{ ex.message }\n#{ ex.backtrace.join("\n") }")
       guards.delete guard
       UI.info("\n#{ guard.class.name } has just been fired")
-      return ex
+
+      ex
     end
 
+    # Add a Guard to use.
+    #
+    # @param [String] name the Guard name
+    # @param [Array<Watcher>] watchers the list of declared watchers
+    # @param [Array<Hash>] callbacks the list of callbacks
+    # @param [Hash] the Guard options
+    #
     def add_guard(name, watchers = [], callbacks = [], options = {})
       if name.to_sym == :ego
-        UI.deprecation("Guard::Ego is now part of Guard. You can remove it from your Guardfile.")
+        UI.deprecation('Guard::Ego is now part of Guard. You can remove it from your Guardfile.')
       else
         guard_class = get_guard_class(name)
         callbacks.each { |callback| Hook.add_callback(callback[:listener], guard_class, callback[:events]) }
@@ -124,10 +175,19 @@ module Guard
       end
     end
 
+    # Add a Guard group.
+    #
+    # @param [String] name the group name
+    #
     def add_group(name)
       @groups << name.to_sym unless name.nil?
     end
 
+    # Tries to load the Guard main class.
+    #
+    # @param [String] name the name of the Guard
+    # @return [Class, nil] the loaded class
+    #
     def get_guard_class(name)
       name        = name.to_s
       try_require = false
@@ -148,6 +208,11 @@ module Guard
       end
     end
 
+    # Locate a path to a Guard gem.
+    #
+    # @param [String] name the name of the Guard without the prefix `guard-`
+    # @return [String] the full path to the Guard gem
+    #
     def locate_guard(name)
       if Gem::Version.create(Gem::VERSION) >= Gem::Version.create('1.8.0')
         Gem::Specification.find_by_name("guard-#{ name }").full_gem_path
@@ -158,8 +223,10 @@ module Guard
       UI.error "Could not find 'guard-#{ name }' gem path."
     end
 
-    ##
     # Returns a list of guard Gem names installed locally.
+    #
+    # @return [Array<String>] a list of guard gem names
+    #
     def guard_gem_names
       if Gem::Version.create(Gem::VERSION) >= Gem::Version.create('1.8.0')
         Gem::Specification.find_all.select { |x| x.name =~ /^guard-/ }
@@ -168,16 +235,19 @@ module Guard
       end.map { |x| x.name.sub /^guard-/, '' }
     end
 
+    # Adds a command logger in debug mode. This wraps common command
+    # execution functions and logs the executed command before execution.
+    #
     def debug_command_execution
       Kernel.send(:alias_method, :original_system, :system)
       Kernel.send(:define_method, :system) do |command, *args|
-        ::Guard::UI.debug "Command execution: #{command} #{args.join(' ')}"
+        ::Guard::UI.debug 'Command execution: #{command} #{args.join(' ')}'
         original_system command, *args
       end
 
-      Kernel.send(:alias_method, :original_backtick, :"`")
+      Kernel.send(:alias_method, :original_backtick, :'`')
-      Kernel.send(:define_method, :"`") do |command|
+      Kernel.send(:define_method, :'`') do |command|
-        ::Guard::UI.debug "Command execution: #{command}"
+        ::Guard::UI.debug 'Command execution: #{command}'
         original_backtick command
       end
     end