lib/peekaboo.rb in peekaboo-0.1.2 vs lib/peekaboo.rb in peekaboo-0.2.0

@@ -1,28 +1,62 @@
 require 'peekaboo/configuration'
 
+# The workhorse of this "Unobtrusive Tracing System".
 module Peekaboo
-  
   class << self
+    # @return [Configuration] the current configuration
     def configuration
       @configuration ||= Configuration.new
     end
     
+    # Convenience method added to assist in configuring the system
+    # ( see {Configuration} for details on all options ).
+    #
+    # @example Configuring the system inside your project
+    #   Peekaboo.configure do |config|
+    #     config.trace_with MyCustomerLogger.new
+    #     config.autoinclude_with SomeBaseClass, AnotherSoloClass
+    #   end
     def configure
       yield configuration
     end
     
+    # Callback used to hook tracing system into any class.
+    #
+    # @param [Class] klass including class
     def included klass
       klass.const_set :PEEKABOO_METHOD_LIST, []
+      klass.instance_variable_set :@_hooked_by_peekaboo, true
       klass.extend SingletonMethods
       
       def klass.method_added name
         Peekaboo.wrap_method self, name if peek_list.include? name
       end
     end
     
-    # @note Should I add execution time to logs?
+    # Modifies a class, and its child classes, to dynamically include module
+    # at runtime. This method is used by {Configuration#autoinclude_with}.
+    #
+    # @param [Class] klass class to modify
+    def setup_autoinclusion klass
+      def klass.method_missing(method_name, *args, &block)
+        if method_name.to_s =~ /^enable_tracing_on$/
+          instance_eval { include Peekaboo }
+          enable_tracing_on *args
+        else
+          super
+        end
+      end
+    end
+    
+    # Takes a class object and method name, aliases the original method,
+    # and redefines the method with injected tracing.
+    #
+    # @note Should I add execution time to tracing? Configurable?
+    #
+    # @param [Class] klass method owner
+    # @param [Symbol] name method to trace
     def wrap_method klass, name
       return if @_adding_a_method
       @_adding_a_method = true
       
       original_method = "original_#{name}"
@@ -46,23 +80,46 @@
       
       @_adding_a_method = false
     end
   end
   
+  # Contains methods added to every class that includes the *Peekaboo* module,
+  # either through _direct_ or _auto_ inclusion.
   module SingletonMethods
+    # @return [Array<Symbol>]
+    #   a list of instance methods that are being traced inside calling class
     def peek_list
       self::PEEKABOO_METHOD_LIST
     end
     
+    # Enables instance method tracing on calling class.
+    #
+    # @example Trace a couple of methods
+    #   class SomeClass
+    #     include Peekaboo
+    #
+    #     def method1; end
+    #     def method2; end
+    #     def method3; end
+    #   end
+    #
+    #   # Tracing will be performed on method1(), method2(), but NOT method3()
+    #   SomeClass.enable_tracing_on :method1, :method2
+    #
+    # @param [*Symbol] method_names
+    #   the list of methods that you want to trace
+    # @raise [RuntimeError]
+    #   when attempting to add a method that is already being traced
     def enable_tracing_on *method_names
+      include Peekaboo unless @_hooked_by_peekaboo
+      
       method_names.each do |method_name|
         unless peek_list.include? method_name
           peek_list << method_name
-          Peekaboo.wrap_method(self, method_name) if self.instance_methods(false).include? method_name.to_s
+          Peekaboo.wrap_method self, method_name if self.instance_methods(false).include? method_name.to_s
         else
           raise "Already tracing `#{method_name}'"
         end
       end
     end
   end
-  
 end