From b55586902dbd3df7b749fd1463dacbe871550adc Mon Sep 17 00:00:00 2001
From: hsbt <hsbt@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Wed, 20 Mar 2019 02:08:34 +0000
Subject: 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
---
 prelude.rb | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

(limited to 'prelude.rb')

diff --git a/prelude.rb b/prelude.rb
index 17f3f5052a..e7125d4de8 100644
--- a/prelude.rb
+++ b/prelude.rb
@@ -133,6 +133,63 @@ class IO
 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@test.rb: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
-- 
cgit v1.2.3