drbrain	2011-05-18 05:16:23 +0900 (Wed, 18 May 2011)

  New Revision: 31618

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=31618

  Log:
    * lib/tracer.rb:  Improve documentation.  Patch by Richard Ramsden.
      [Ruby 1.9 - Feature #4720]

  Modified files:
    trunk/ChangeLog
    trunk/lib/tracer.rb

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 31617)
+++ ChangeLog	(revision 31618)
@@ -1,3 +1,8 @@
+Wed May 18 05:10:35 2011  Eric Hodel  <drbrain@s...>
+
+	* lib/tracer.rb:  Improve documentation.  Patch by Richard Ramsden.
+	  [Ruby 1.9 - Feature #4720]
+
 Wed May 18 04:53:41 2011  Eric Hodel  <drbrain@s...>
 
 	* lib/cmath.rb:  Improve documentation.  Patch by Jason Dew.
Index: lib/tracer.rb
===================================================================
--- lib/tracer.rb	(revision 31617)
+++ lib/tracer.rb	(revision 31618)
@@ -1,12 +1,63 @@
-#   tracer.rb -
-#   	$Release Version: 0.3$
-#   	$Revision: 1.12 $
-#   	by Keiju ISHITSUKA(keiju@i...)
+##
+# = Tracer
 #
-# --
+# Tracer outputs a source level execution trace of a Ruby program. It does
+# this by registering an event handler with <code>Kernel#set_trace_func</code>
+# for processing incoming events.  It also provides methods for filtering
+# unwanted trace output (see Tracer.add_filter, Tracer.on, and Tracer.off).
 #
+# == Example
 #
+# Consider the following ruby script
 #
+#   class A
+#     def square(a)
+#       return a*a
+#     end
+#   end
+#
+#   a = A.new
+#   a.square(5)
+#
+# Running the above script using <code>ruby -r tracer example.rb</code> will
+# output the following trace to STDOUT (Note you can also explicitly
+# <code>require 'tracer'</code>)
+#
+#   #0:<internal:lib/rubygems/custom_require>:38:Kernel:<: -
+#   #0:example.rb:3::-: class A
+#   #0:example.rb:3::C: class A
+#   #0:example.rb:4::-:   def square(a)
+#   #0:example.rb:7::E: end
+#   #0:example.rb:9::-: a = A.new
+#   #0:example.rb:10::-: a.square(5)
+#   #0:example.rb:4:A:>:   def square(a)
+#   #0:example.rb:5:A:-:     return a*a
+#   #0:example.rb:6:A:<:   end
+#    |  |         | |  |
+#    |  |         | |   ---------------------+ event
+#    |  |         |  ------------------------+ class
+#    |  |          --------------------------+ line
+#    |   ------------------------------------+ filename
+#     ---------------------------------------+ thread
+#
+# Symbol table used for displaying incoming events:
+#
+# <tt>}</tt>:: call a C-language routine
+# <tt>{</tt>:: return from a C-language routine
+# <tt>></tt>:: call a Ruby method
+# <tt>C</tt>:: start a class or module definition
+# <tt>E</tt>:: finish a class or module definition
+# <tt>-</tt>:: execute code on a new line
+# <tt>^</tt>:: raise an exception
+# <tt><</tt>:: return from a Ruby method
+#
+# == Copyright
+#
+# by Keiju ISHITSUKA(keiju@i...)
+#
+#--
+# $Release Version: 0.3$
+# $Revision: 1.12 $
 require "thread"
 
 #
@@ -14,24 +65,29 @@
 #
 class Tracer
   class << self
+    # display additional debug information (defaults to false)
     attr_accessor :verbose
     alias verbose? verbose
 
+    # output stream used to output trace (defaults to STDOUT)
     attr_accessor :stdout
+
+    # mutex lock used by tracer for displaying trace output
     attr_reader :stdout_mutex
 
-    # display process id?
+    # display process id in trace output (defaults to false)
     attr_accessor :display_process_id
     alias display_process_id? display_process_id
 
-    # display thread id?
+    # display thread id in trace output (defaults to true)
     attr_accessor :display_thread_id
     alias display_thread_id? display_thread_id
 
-    # display builtin method call?
+    # display C-routine calls in trace output (defaults to false)
     attr_accessor :display_c_call
     alias display_c_call? display_c_call
   end
+
   Tracer::stdout = STDOUT
   Tracer::verbose = false
   Tracer::display_process_id = false
@@ -40,6 +96,7 @@
 
   @stdout_mutex = Mutex.new
 
+  # Symbol table used for displaying trace information
   EVENT_SYMBOL = {
     "line" => "-",
     "call" => ">",
@@ -52,7 +109,7 @@
     "unknown" => "?"
   }
 
-  def initialize
+  def initialize # :nodoc:
     @threads = Hash.new
     if defined? Thread.main
       @threads[Thread.main.object_id] = 0
@@ -65,11 +122,11 @@
     @filters = []
   end
 
-  def stdout
+  def stdout # :nodoc:
     Tracer.stdout
   end
 
-  def on
+  def on # :nodoc:
     if block_given?
       on
       begin
@@ -83,20 +140,20 @@
     end
   end
 
-  def off
+  def off # :nodoc:
     set_trace_func nil
     stdout.print "Trace off\n" if Tracer.verbose?
   end
 
-  def add_filter(p = proc)
+  def add_filter(p = proc) # :nodoc:
     @filters.push p
   end
 
-  def set_get_line_procs(file, p = proc)
+  def set_get_line_procs(file, p = proc) # :nodoc:
     @get_line_procs[file] = p
   end
 
-  def get_line(file, line)
+  def get_line(file, line) # :nodoc:
     if p = @get_line_procs[file]
       return p.call(line)
     end
@@ -121,7 +178,7 @@
     end
   end
 
-  def get_thread_no
+  def get_thread_no # :nodoc:
     if no = @threads[Thread.current.object_id]
       no
     else
@@ -129,7 +186,7 @@
     end
   end
 
-  def trace_func(event, file, line, id, binding, klass, *)
+  def trace_func(event, file, line, id, binding, klass, *) # :nodoc:
     return if file == __FILE__
 
     for p in @filters
@@ -159,7 +216,24 @@
 
   end
 
+  # Reference to singleton instance of Tracer
   Single = new
+
+  ##
+  # Start tracing
+  #
+  # === Example
+  #
+  #   Tracer.on
+  #   # code to trace here
+  #   Tracer.off
+  #
+  # You can also pass a block:
+  #
+  #   Tracer.on {
+  #     # trace everything in this block
+  #   }
+
   def Tracer.on
     if block_given?
       Single.on{yield}
@@ -168,19 +242,42 @@
     end
   end
 
+  ##
+  # Disable tracing
+
   def Tracer.off
     Single.off
   end
 
+  ##
+  # Register an event handler <code>p</code> which is called everytime a line
+  # in +file_name+ is executed.
+  #
+  # Example:
+  #
+  #   Tracer.set_get_line_procs("example.rb", lambda { |line|
+  #     puts "line number executed is #{line}"
+  #   })
+
   def Tracer.set_get_line_procs(file_name, p = proc)
     Single.set_get_line_procs(file_name, p)
   end
 
+  ##
+  # Used to filter unwanted trace output
+  #
+  # Example which only outputs lines of code executed within the Kernel class:
+  #
+  #   Tracer.add_filter do |event, file, line, id, binding, klass, *rest|
+  #     "Kernel" == klass.to_s
+  #   end
+
   def Tracer.add_filter(p = proc)
     Single.add_filter(p)
   end
 end
 
+# :stopdoc:
 SCRIPT_LINES__ = {} unless defined? SCRIPT_LINES__
 
 if $0 == __FILE__
@@ -193,3 +290,4 @@
 elsif caller.count {|bt| /\A<internal:[^<>]+>:/ !~ bt} <= 1
   Tracer.on
 end
+# :startdoc:

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/