From 98ee45003789ee538899e4470fe233b2cd788884 Mon Sep 17 00:00:00 2001
From: Michael Kessler <michi@netzpiraten.ch>
Date: Tue, 20 Sep 2011 13:06:35 +0200
Subject: [PATCH] Initial notifier yardoc.

---
 lib/guard/notifier.rb | 74 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/lib/guard/notifier.rb b/lib/guard/notifier.rb
index e9ea811..e9b7f8f 100644
--- a/lib/guard/notifier.rb
+++ b/lib/guard/notifier.rb
@@ -3,13 +3,28 @@ require 'pathname'
 require 'guard/ui'
 
 module Guard
+
+  # The notifier class handles cross-platform system notifications that supports:
+  # - Growl on Mac OS X
+  # - Libnotify on Linux
+  # - Notifu on Windows
+  #
   module Notifier
+
+    # Application name as shown in the specific notification settings
     APPLICATION_NAME = "Guard"
 
+    # Turn notifications of.
+    #
     def self.turn_off
       ENV["GUARD_NOTIFY"] = 'false'
     end
 
+    # Turn notifications on. This tries to load the platform
+    # specific notification library.
+    #
+    # @return [Boolean] whether the notification could be enabled.
+    #
     def self.turn_on
       ENV["GUARD_NOTIFY"] = 'true'
       case RbConfig::CONFIG['target_os']
@@ -22,6 +37,15 @@ module Guard
       end
     end
 
+    # Show a message with the system notification.
+    #
+    # @see .image_path
+    #
+    # @param [String] the message to show
+    # @param [Hash] options the notification options
+    # @option options [Symbol, String] image the image symbol or path to an image
+    # @option options [String] title the notification title
+    #
     def self.notify(message, options = {})
       if enabled?
         image = options.delete(:image) || :success
@@ -38,12 +62,23 @@ module Guard
       end
     end
 
+    # Test if the notifications are enabled and available.
+    #
+    # @return [Boolean] whether the notifications are available
+    #
     def self.enabled?
       ENV["GUARD_NOTIFY"] == 'true'
     end
 
   private
 
+    # Send a message to Growl either with the growl gem or the growl_notify gem.
+    #
+    # @param [String] title the notification title
+    # @param [String] message the message to show
+    # @param [Symbol, String] the image to user
+    # @param [Hash] options the growl options
+    #
     def self.notify_mac(title, message, image, options)
       require_growl # need for guard-rspec formatter that is called out of guard scope
 
@@ -61,18 +96,42 @@ module Guard
       end
     end
 
+    # Send a message to libnotify.
+    #
+    # @param [String] title the notification title
+    # @param [String] message the message to show
+    # @param [Symbol, String] the image to user
+    # @param [Hash] options the libnotify options
+    #
     def self.notify_linux(title, message, image, options)
       require_libnotify # need for guard-rspec formatter that is called out of guard scope
       default_options = { :body => message, :summary => title, :icon_path => image_path(image), :transient => true }
       Libnotify.show default_options.merge(options) if enabled?
     end
 
+    # Send a message to notifu.
+    #
+    # @param [String] title the notification title
+    # @param [String] message the message to show
+    # @param [Symbol, String] the image to user
+    # @param [Hash] options the notifu options
+    #
     def self.notify_windows(title, message, image, options)
       require_rbnotifu # need for guard-rspec formatter that is called out of guard scope
       default_options = { :message => message, :title => title, :type => image_level(image), :time => 3 }
       Notifu.show default_options.merge(options) if enabled?
     end
 
+    # Get the image path for an image symbol.
+    #
+    # Known symbols are:
+    # - failed
+    # - pending
+    # - success
+    #
+    # @param [Symbol] image the image name
+    # @return [String] the image path
+    #
     def self.image_path(image)
       images_path = Pathname.new(File.dirname(__FILE__)).join('../../images')
       case image
@@ -88,6 +147,11 @@ module Guard
       end
     end
 
+    # The notification level type for the given image.
+    #
+    # @param [Symbol] image the image
+    # @return [Symbol] the level
+    #
     def self.image_level(image)
       case image
       when :failed
@@ -101,6 +165,9 @@ module Guard
       end
     end
 
+    # Try to safely load growl and turns notifications
+    # off on load failure.
+    #
     def self.require_growl
       begin
         require 'growl_notify'
@@ -119,6 +186,9 @@ module Guard
       UI.info "Please install growl_notify or growl gem for Mac OS X notification support and add it to your Gemfile"
     end
 
+    # Try to safely load libnotify and turns notifications
+    # off on load failure.
+    #
     def self.require_libnotify
       require 'libnotify'
     rescue LoadError
@@ -126,11 +196,15 @@ module Guard
       UI.info "Please install libnotify gem for Linux notification support and add it to your Gemfile"
     end
 
+    # Try to safely load rb-notifu and turns notifications
+    # off on load failure.
+    #
     def self.require_rbnotifu
       require 'rb-notifu'
     rescue LoadError
       turn_off
       UI.info "Please install rb-notifu gem for Windows notification support and add it to your Gemfile"
     end
+
   end
 end