hsbt	2019-03-20 11:08:34 +0900 (Wed, 20 Mar 2019)

  New Revision: 67313

  https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=67313

  Log:
    Improve TracePoint docs.
    
      * Mention new :script_compiled event;
      * Deduplicate __enable/enable methods;
      * Document target: and target_line: arguments.
    
      [Bug #15484][ruby-core:90801]
    
      Co-authored-by: zverok <zverok.offline@g...>

  Modified files:
    trunk/prelude.rb
    trunk/vm_trace.c
Index: prelude.rb
===================================================================
--- prelude.rb	(revision 67312)
+++ prelude.rb	(revision 67313)
@@ -133,6 +133,63 @@ class IO https://github.com/ruby/ruby/blob/trunk/prelude.rb#L133
 end
 
 class TracePoint
+  # call-seq:
+  #  trace.enable(target: nil, target_line: nil)    -> true or false
+  #  trace.enable(target: nil, target_line: nil) { block }  -> obj
+  #
+  # Activates the trace
+  #
+  # Return +true+ if trace was enabled.
+  # Return +false+ if trace was disabled.
+  #
+  #   trace.enabled?  #=> false
+  #   trace.enable    #=> false (previous state)
+  #                   #   trace is enabled
+  #   trace.enabled?  #=> true
+  #   trace.enable    #=> true (previous state)
+  #                   #   trace is still enabled
+  #
+  # If a block is given, the trace will only be enabled within the scope of the
+  # block.
+  #
+  #    trace.enabled?
+  #    #=> false
+  #
+  #    trace.enable do
+  #        trace.enabled?
+  #        # only enabled for this block
+  #    end
+  #
+  #    trace.enabled?
+  #    #=> false
+  #
+  # <i>target</i> and <i>target_line</i> parameters are used to limit tracing
+  # only to specified code objects. <i>target</i> should be a code object for
+  # which RubyVM::InstructionSequence.of will return instruction sequence.
+  #
+  #    t = TracePoint.new(:line) { |tp| p tp }
+  #
+  #    def m1
+  #        p 1
+  #    end
+  #
+  #    def m2
+  #        p 2
+  #    end
+  #
+  #    t.enable(target: method(:m1))
+  #
+  #    m1
+  #    # prints #<TracePoint:line@t...:5 in `m1'>
+  #    m2
+  #    # prints nothing
+  #
+  #
+  # Note: You cannot access event hooks within the +enable+ block.
+  #
+  #    trace.enable { p tp.lineno }
+  #    #=> RuntimeError: access from outside
+  #
   def enable target: nil, target_line: nil, target_thread: nil, &blk
     self.__enable target, target_line, target_thread, &blk
   end
Index: vm_trace.c
===================================================================
--- vm_trace.c	(revision 67312)
+++ vm_trace.c	(revision 67313)
@@ -1058,7 +1058,8 @@ tracepoint_attr_path(VALUE tpval) https://github.com/ruby/ruby/blob/trunk/vm_trace.c#L1058
 }
 
 /*
- * Return the parameters of the method or block that the current hook belongs to
+ * Return the parameters definition of the method or block that the
+ * current hook belongs to. Format is the same as for Method#parameters
  */
 static VALUE
 tracepoint_attr_parameters(VALUE tpval)
@@ -1361,42 +1362,8 @@ rb_hook_list_remove_tracepoint(rb_hook_l https://github.com/ruby/ruby/blob/trunk/vm_trace.c#L1362
     list->events = events;
 }
 
-/*
- * call-seq:
- *	trace.enable		-> true or false
- *	trace.enable { block }	-> obj
- *
- * Activates the trace
- *
- * Return true if trace was enabled.
- * Return false if trace was disabled.
- *
- *	trace.enabled?  #=> false
- *	trace.enable    #=> false (previous state)
- *                      #   trace is enabled
- *	trace.enabled?  #=> true
- *	trace.enable    #=> true (previous state)
- *                      #   trace is still enabled
- *
- * If a block is given, the trace will only be enabled within the scope of the
- * block.
- *
- *	trace.enabled?
- *	#=> false
- *
- *	trace.enable do
- *	    trace.enabled?
- *	    # only enabled for this block
- *	end
- *
- *	trace.enabled?
- *	#=> false
- *
- * Note: You cannot access event hooks within the block.
- *
- *	trace.enable { p tp.lineno }
- *	#=> RuntimeError: access from outside
- *
+/* :nodoc:
+ * Docs for the TracePointe#enable are in prelude.rb
  */
 static VALUE
 tracepoint_enable_m(VALUE tpval, VALUE target, VALUE target_line, VALUE target_thread)
@@ -1792,6 +1759,7 @@ Init_vm_trace(void) https://github.com/ruby/ruby/blob/trunk/vm_trace.c#L1759
      * +:thread_begin+:: event hook at thread beginning
      * +:thread_end+:: event hook at thread ending
      * +:fiber_switch+:: event hook at fiber switch
+     * +:script_compiled+:: new Ruby code compiled (with +eval+, +load+ or +require+)
      *
      */
     rb_cTracePoint = rb_define_class("TracePoint", rb_cObject);

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