informer.rb in ramaze-0.1.4

- old
+ new

@@ -26,10 +26,21 @@
       :debug => :yellow,
       :warn  => :red,
       :error => :red,
     }
 
+    # Create a new instance of Informer.
+    # You can spcify
+    #
+    # Examples:
+    #   Informer.new                    #=> logs to stdout with all levels being
+    #                                       shown.
+    #   Informer.new($stderr)           #=> same, but to stderr
+    #   Informer.new("foo.log")         #=> same, but logs to the file foo.log
+    #                                       (or creates it if it doesn't exist yet)
+    #   Informer.new($stdout, [:info])  #=> show only #info messages to stdout.
+
     def initialize(out = $stdout, log_levels = [:debug, :error, :info, :warn])
       @colorize = false
 
       @out =
         case out
@@ -52,17 +63,21 @@
       end
 
       @log_levels = log_levels
     end
 
+    # Close the file we log to if it isn't closed already.
+
     def shutdown
       if @out.respond_to?(:close)
         Inform.debug("close, #{@out.inspect}")
         @out.close
       end
     end
 
+    # Integration to Informing.
+
     def inform tag, *messages
       return if closed? || !@log_levels.include?(tag)
       messages.flatten!
 
       prefix = tag.to_s.upcase.ljust(5)
@@ -77,10 +92,13 @@
       end
 
       @out.flush if @out.respond_to?(:flush)
     end
 
+    # Takes the prefix (tag), text and timestamp and applies it to
+    # the :format trait.
+
     def log_interpolate prefix, text, time = timestamp
       message = class_trait[:format].dup
 
       vars = { '%time' => time, '%prefix' => prefix, '%text' => text }
       vars.each{|from, to| message.gsub!(from, to) }
@@ -94,9 +112,11 @@
 
     def timestamp
       mask = class_trait[:timestamp]
       Time.now.strftime(mask || "%Y-%m-%d %H:%M:%S")
     end
+
+    # is @out closed?
 
     def closed?
       @out.respond_to?(:closed?) and @out.closed?
     end
   end