From ab91117ed76cfb5debfdb7f3885bb1dc619f46c5 Mon Sep 17 00:00:00 2001
From: Michael Kessler <michi@netzpiraten.ch>
Date: Tue, 20 Sep 2011 12:54:36 +0200
Subject: [PATCH] Add yardoc to the UI class.

---
 lib/guard/ui.rb | 86 ++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 67 insertions(+), 19 deletions(-)

diff --git a/lib/guard/ui.rb b/lib/guard/ui.rb
index a52b42a..4783ded 100644
--- a/lib/guard/ui.rb
+++ b/lib/guard/ui.rb
@@ -1,30 +1,39 @@
 module Guard
+
+  # The UI class helps to format messages for the user.
+  #
   module UI
 
     ANSI_ESCAPE_BRIGHT = "1"
 
-    ANSI_ESCAPE_BLACK = "30"
-    ANSI_ESCAPE_RED = "31"
-    ANSI_ESCAPE_GREEN = "32"
-    ANSI_ESCAPE_YELLOW = "33"
-    ANSI_ESCAPE_BLUE = "34"
+    ANSI_ESCAPE_BLACK   = "30"
+    ANSI_ESCAPE_RED     = "31"
+    ANSI_ESCAPE_GREEN   = "32"
+    ANSI_ESCAPE_YELLOW  = "33"
+    ANSI_ESCAPE_BLUE    = "34"
     ANSI_ESCAPE_MAGENTA = "35"
-    ANSI_ESCAPE_CYAN = "36"
-    ANSI_ESCAPE_WHITE = "37"
+    ANSI_ESCAPE_CYAN    = "36"
+    ANSI_ESCAPE_WHITE   = "37"
 
-    ANSI_ESCAPE_BGBLACK = "40"
-    ANSI_ESCAPE_BGRED = "41"
-    ANSI_ESCAPE_BGGREEN = "42"
-    ANSI_ESCAPE_BGYELLOW = "43"
-    ANSI_ESCAPE_BGBLUE = "44"
+    ANSI_ESCAPE_BGBLACK   = "40"
+    ANSI_ESCAPE_BGRED     = "41"
+    ANSI_ESCAPE_BGGREEN   = "42"
+    ANSI_ESCAPE_BGYELLOW  = "43"
+    ANSI_ESCAPE_BGBLUE    = "44"
     ANSI_ESCAPE_BGMAGENTA = "45"
-    ANSI_ESCAPE_BGCYAN = "46"
-    ANSI_ESCAPE_BGWHITE = "47"
+    ANSI_ESCAPE_BGCYAN    = "46"
+    ANSI_ESCAPE_BGWHITE   = "47"
 
     class << self
 
       color_enabled = nil
 
+      # Show an info message.
+      #
+      # @param [String] message the message to show
+      # @param [Hash] options the options
+      # @option options [Boolean] reset whether to clean the output before
+      #
       def info(message, options = {})
         unless ENV["GUARD_ENV"] == "test"
           reset_line if options[:reset]
@@ -32,13 +41,25 @@ module Guard
         end
       end
 
-      def error(message, options={})
+      # Show a red error message that is prefixed with ERROR.
+      #
+      # @param [String] message the message to show
+      # @param [Hash] options the options
+      # @option options [Boolean] reset whether to clean the output before
+      #
+      def error(message, options = {})
         unless ENV["GUARD_ENV"] == "test"
           reset_line if options[:reset]
           puts color('ERROR: ', :red) + message
         end
       end
 
+      # Show a red deprecation message that is prefixed with DEPRECATION.
+      #
+      # @param [String] message the message to show
+      # @param [Hash] options the options
+      # @option options [Boolean] reset whether to clean the output before
+      #
       def deprecation(message, options = {})
         unless ENV["GUARD_ENV"] == "test"
           reset_line if options[:reset]
@@ -46,43 +67,69 @@ module Guard
         end
       end
 
-      def debug(message, options={})
+      # Show a debug message that is prefixed with DEBUG and a timestampe.
+      #
+      # @param [String] message the message to show
+      # @param [Hash] options the options
+      # @option options [Boolean] reset whether to clean the output before
+      #
+      def debug(message, options={ })
         unless ENV["GUARD_ENV"] == "test"
           reset_line if options[:reset]
           puts color("DEBUG (#{Time.now.strftime('%T')}): ", :yellow) + message if ::Guard.options && ::Guard.options[:debug]
         end
       end
 
+      # Reset a line.
+      #
       def reset_line
         print(color_enabled? ? "\r\e[0m" : "\r\n")
       end
 
+      # Clear the output.
+      #
       def clear
         system("clear;")
       end
 
-    private
+      private
 
+      # Reset a color sequence.
+      #
       # @deprecated
+      # @param [String] text the text
+      #
       def reset_color(text)
         deprecation('UI.reset_color(text) is deprecated, please use color(text, "") instead.')
         color(text, "")
       end
 
+      # Colorizes a text message.
+      #
+      # @example
+      #   color("Hello World", :red, :bright)
+      #
+      # @param [String] the text to colorize
+      # @param [Array] color_options
+      #
       def color(text, *color_options)
         color_code = ""
         color_options.each do |color_option|
           color_option = color_option.to_s
           if color_option != ""
             if !(color_option =~ /\d+/)
-              color_option = const_get("ANSI_ESCAPE_#{color_option.upcase}")
+              color_option = const_get("ANSI_ESCAPE_#{ color_option.upcase }")
             end
             color_code += ";" + color_option
           end
         end
-        color_enabled? ? "\e[0#{color_code}m#{text}\e[0m" : text
+        color_enabled? ? "\e[0#{ color_code }m#{ text }\e[0m" : text
       end
 
+      # Checks if color output can be enabled.
+      #
+      # @return [Boolean] whether color is enabled or not
+      #
       def color_enabled?
         if @color_enabled.nil?
           if RbConfig::CONFIG['target_os'] =~ /mswin|mingw/i
@@ -102,6 +149,7 @@ module Guard
             @color_enabled = true
           end
         end
+
         @color_enabled
       end