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@gmail.com>

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@67313 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 5 insertions, 37 deletions

diff --git a/vm_trace.c b/vm_trace.c
index 78e35143c1..7fb8b7a24f 100644
--- a/vm_trace.c
+++ b/vm_trace.c
@@ -1058,7 +1058,8 @@ tracepoint_attr_path(VALUE tpval)
 }
 
 /*
- * 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_list_t *list, VALUE tpval)
     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)
      * +: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);