From 5e8c9b4b284d3200dc74ff41243288caf0d7b4f6 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Fri, 13 Dec 2024 05:44:15 +0800 Subject: [PATCH] [DOC] Fix grammar errors, typos, and improve readability of trace_point.rb (#12150) --- trace_point.rb | 347 ++++++++++++++++++++++++------------------------- 1 file changed, 171 insertions(+), 176 deletions(-) diff --git a/trace_point.rb b/trace_point.rb index b136e9b399..682398ec3f 100644 --- a/trace_point.rb +++ b/trace_point.rb @@ -1,95 +1,93 @@ # loaded from vm_trace.c # A class that provides the functionality of Kernel#set_trace_func in a -# nice Object-Oriented API. +# well-structured Object-Oriented API. # # == Example # -# We can use TracePoint to gather information specifically for exceptions: +# Use TracePoint to gather information specifically for exceptions: # -# trace = TracePoint.new(:raise) do |tp| -# p [tp.lineno, tp.event, tp.raised_exception] -# end -# #=> # +# trace = TracePoint.new(:raise) do |tp| +# p [tp.lineno, tp.event, tp.raised_exception] +# end +# #=> # # -# trace.enable -# #=> false +# trace.enable #=> false # -# 0 / 0 -# #=> [5, :raise, #] +# 0 / 0 +# #=> [5, :raise, #] # # == Events # -# If you don't specify the type of events you want to listen for, +# If you don't specify the types of events you want to listen for, # TracePoint will include all available events. # -# *Note* do not depend on current event set, as this list is subject to -# change. Instead, it is recommended you specify the type of events you +# *Note:* Do not depend on the current event set, as this list is subject to +# change. Instead, it is recommended to specify the types of events you # want to use. # # To filter what is traced, you can pass any of the following as +events+: # -# +:line+:: execute an expression or statement on a new line -# +:class+:: start a class or module definition -# +:end+:: finish a class or module definition -# +:call+:: call a Ruby method -# +:return+:: return from a Ruby method -# +:c_call+:: call a C-language routine -# +:c_return+:: return from a C-language routine -# +:raise+:: raise an exception -# +:rescue+:: rescue an exception -# +:b_call+:: event hook at block entry -# +:b_return+:: event hook at block ending -# +:a_call+:: event hook at all calls (+call+, +b_call+, and +c_call+) -# +:a_return+:: event hook at all returns (+return+, +b_return+, and +c_return+) -# +: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+) +# +:line+:: Execute an expression or statement on a new line. +# +:class+:: Start a class or module definition. +# +:end+:: Finish a class or module definition. +# +:call+:: Call a Ruby method. +# +:return+:: Return from a Ruby method. +# +:c_call+:: Call a C-language routine. +# +:c_return+:: Return from a C-language routine. +# +:raise+:: Raise an exception. +# +:rescue+:: Rescue an exception. +# +:b_call+:: Event hook at block entry. +# +:b_return+:: Event hook at block ending. +# +:a_call+:: Event hook at all calls (+call+, +b_call+, and +c_call+). +# +:a_return+:: Event hook at all returns (+return+, +b_return+, and +c_return+). +# +: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+). # class TracePoint # call-seq: - # TracePoint.new(*events) { |obj| block } -> obj + # TracePoint.new(*events) { |tp| block } -> tp # # Returns a new TracePoint object, not enabled by default. # - # Next, in order to activate the trace, you must use TracePoint#enable + # To activate the TracePoint object, use TracePoint#enable: # - # trace = TracePoint.new(:call) do |tp| - # p [tp.lineno, tp.defined_class, tp.method_id, tp.event] - # end - # #=> # + # trace = TracePoint.new(:call) do |tp| + # p [tp.lineno, tp.defined_class, tp.method_id, tp.event] + # end + # #=> # # - # trace.enable - # #=> false + # trace.enable #=> false # - # puts "Hello, TracePoint!" - # # ... - # # [48, IRB::Notifier::AbstractNotifier, :printf, :call] - # # ... + # puts "Hello, TracePoint!" + # # ... + # # [48, IRB::Notifier::AbstractNotifier, :printf, :call] + # # ... # - # When you want to deactivate the trace, you must use TracePoint#disable + # To deactivate the trace, use TracePoint#disable. # - # trace.disable + # trace.disable # # See TracePoint@Events for possible events and more information. # - # A block must be given, otherwise an ArgumentError is raised. + # A block must be given; otherwise, an ArgumentError is raised. # # If the trace method isn't included in the given events filter, a # RuntimeError is raised. # - # TracePoint.trace(:line) do |tp| - # p tp.raised_exception - # end - # #=> RuntimeError: 'raised_exception' not supported by this event + # TracePoint.trace(:line) do |tp| + # p tp.raised_exception + # end + # #=> RuntimeError: 'raised_exception' not supported by this event # - # If the trace method is called outside block, a RuntimeError is raised. + # If the trace method is called outside a block, a RuntimeError is raised. # - # TracePoint.trace(:line) do |tp| - # $tp = tp - # end - # $tp.lineno #=> access from outside (RuntimeError) + # TracePoint.trace(:line) do |tp| + # $tp = tp + # end + # $tp.lineno #=> access from outside (RuntimeError) # # Access from other threads is also forbidden. # @@ -98,38 +96,38 @@ class TracePoint Primitive.tracepoint_new_s(events) end - # call-seq: - # trace.inspect -> string + # call-seq: + # trace.inspect -> string # - # Return a string containing a human-readable TracePoint - # status. + # Returns a string containing a human-readable TracePoint + # status. def inspect Primitive.tracepoint_inspect end # call-seq: - # TracePoint.stat -> obj + # TracePoint.stat -> obj # - # Returns internal information of TracePoint. + # Returns internal information of TracePoint. # - # The contents of the returned value are implementation specific. - # It may be changed in future. + # The contents of the returned value are implementation-specific + # and may change in the future. # - # This method is only for debugging TracePoint itself. + # This method is only for debugging TracePoint itself. def self.stat Primitive.tracepoint_stat_s end # call-seq: - # TracePoint.trace(*events) { |obj| block } -> obj + # TracePoint.trace(*events) { |tp| block } -> obj # - # A convenience method for TracePoint.new, that activates the trace + # A convenience method for TracePoint.new that activates the trace # automatically. # - # trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] } - # #=> # + # trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] } + # #=> # # - # trace.enabled? #=> true + # trace.enabled? #=> true # def self.trace(*events) Primitive.attr! :use_block @@ -139,14 +137,13 @@ class TracePoint # call-seq: # TracePoint.allow_reentry { block } # - # In general, while a TracePoint callback is running, + # Generally, while a TracePoint callback is running, # other registered callbacks are not called to avoid - # confusion by reentrance. - # This method allows the reentrance in a given block. - # This method should be used carefully, otherwise the callback - # can be easily called infinitely. + # confusion from reentrance. + # This method allows reentrance within a given block. + # Use this method carefully to avoid infinite callback invocation. # - # If this method is called when the reentrance is already allowed, + # If called when reentrance is already allowed, # it raises a RuntimeError. # # Example: @@ -155,7 +152,7 @@ class TracePoint # # --------------- # # line_handler = TracePoint.new(:line) do |tp| - # next if tp.path != __FILE__ # only work in this file + # next if tp.path != __FILE__ # Only works in this file # puts "Line handler" # binding.eval("class C; end") # end.enable @@ -167,16 +164,16 @@ class TracePoint # class B # end # - # # This script will print "Class handler" only once: when inside :line - # # handler, all other handlers are ignored + # # This script will print "Class handler" only once: when inside the :line + # # handler, all other handlers are ignored. # # # # With reentry # # ------------ # # line_handler = TracePoint.new(:line) do |tp| - # next if tp.path != __FILE__ # only work in this file - # next if (__LINE__..__LINE__+3).cover?(tp.lineno) # don't be invoked from itself + # next if tp.path != __FILE__ # Only works in this file + # next if (__LINE__..__LINE__+3).cover?(tp.lineno) # Prevent infinite calls # puts "Line handler" # TracePoint.allow_reentry { binding.eval("class C; end") } # end.enable @@ -188,14 +185,15 @@ class TracePoint # class B # end # - # # This wil print "Class handler" twice: inside allow_reentry block in :line + # # This will print "Class handler" twice: inside the allow_reentry block in the :line # # handler, other handlers are enabled. # # Note that the example shows the principal effect of the method, but its - # practical usage is for debugging libraries that sometimes require other libraries - # hooks to not be affected by debugger being inside trace point handling. Precautions - # should be taken against infinite recursion in this case (note that we needed to filter - # out calls by itself from :line handler, otherwise it will call itself infinitely). + # practical usage is for debugging libraries that sometimes require other libraries' + # hooks to not be affected by the debugger being inside trace point handling. + # Precautions should be taken against infinite recursion in this case + # (note that we needed to filter out calls by itself from the :line handler, + # otherwise it would call itself infinitely). # def self.allow_reentry Primitive.attr! :use_block @@ -203,13 +201,13 @@ class TracePoint end # call-seq: - # trace.enable(target: nil, target_line: nil, target_thread: nil) -> true or false - # trace.enable(target: nil, target_line: nil, target_thread: :default) { block } -> obj + # trace.enable(target: nil, target_line: nil, target_thread: nil) -> true or false + # trace.enable(target: nil, target_line: nil, target_thread: :default) { block } -> obj # # Activates the trace. # - # Returns +true+ if trace was enabled. - # Returns +false+ if trace was disabled. + # Returns +true+ if the trace was enabled. + # Returns +false+ if the trace was disabled. # # trace.enabled? #=> false # trace.enable #=> false (previous state) @@ -218,47 +216,45 @@ class TracePoint # trace.enable #=> true (previous state) # # trace is still enabled # - # If a block is given, the trace will only be enabled during the block call. + # If a block is given, the trace will only be enabled during the block execution. # If target and target_line are both nil, then target_thread will default # to the current thread if a block is given. # - # trace.enabled? - # #=> false + # trace.enabled? #=> false # - # trace.enable do - # trace.enabled? - # # only enabled for this block and thread - # end + # trace.enable do + # trace.enabled? + # # Only enabled for this block and thread + # end # - # trace.enabled? - # #=> false + # trace.enabled? #=> false # - # +target+, +target_line+ and +target_thread+ parameters are used to - # limit tracing only to specified code objects. +target+ should be a + # The +target+, +target_line+, and +target_thread+ parameters are used to + # limit tracing to specified code objects. +target+ should be a # code object for which RubyVM::InstructionSequence.of will return # an instruction sequence. # - # t = TracePoint.new(:line) { |tp| p tp } + # t = TracePoint.new(:line) { |tp| p tp } # - # def m1 - # p 1 - # end + # def m1 + # p 1 + # end # - # def m2 - # p 2 - # end + # def m2 + # p 2 + # end # - # t.enable(target: method(:m1)) + # t.enable(target: method(:m1)) # - # m1 - # # prints # - # m2 - # # prints nothing + # m1 + # # Prints # + # m2 + # # Prints nothing # # Note: You cannot access event hooks within the +enable+ block. # - # trace.enable { p tp.lineno } - # #=> RuntimeError: access from outside + # trace.enable { p tp.lineno } + # #=> RuntimeError: access from outside # def enable(target: nil, target_line: nil, target_thread: :default) Primitive.attr! :use_block @@ -266,130 +262,129 @@ class TracePoint end # call-seq: - # trace.disable -> true or false - # trace.disable { block } -> obj + # trace.disable -> true or false + # trace.disable { block } -> obj # - # Deactivates the trace + # Deactivates the trace. # - # Return true if trace was enabled. - # Return false if trace was disabled. + # Returns +true+ if the trace was enabled. + # Returns +false+ if the trace was disabled. # - # trace.enabled? #=> true - # trace.disable #=> true (previous status) - # trace.enabled? #=> false - # trace.disable #=> false + # trace.enabled? #=> true + # trace.disable #=> true (previous status) + # trace.enabled? #=> false + # trace.disable #=> false # - # If a block is given, the trace will only be disable within the scope of the + # If a block is given, the trace will only be disabled within the scope of the # block. # - # trace.enabled? - # #=> true + # trace.enabled? #=> true # - # trace.disable do - # trace.enabled? - # # only disabled for this block - # end + # trace.disable do + # trace.enabled? + # # Only disabled for this block + # end # - # trace.enabled? - # #=> true + # trace.enabled? #=> true # # Note: You cannot access event hooks within the block. # - # trace.disable { p tp.lineno } - # #=> RuntimeError: access from outside + # trace.disable { p tp.lineno } + # #=> RuntimeError: access from outside + # def disable Primitive.attr! :use_block Primitive.tracepoint_disable_m end # call-seq: - # trace.enabled? -> true or false + # trace.enabled? -> true or false # - # The current status of the trace + # Returns the current status of the trace. def enabled? Primitive.tracepoint_enabled_p end - # Type of event + # Returns the type of event. # # See TracePoint@Events for more information. def event Primitive.tracepoint_attr_event end - # Line number of the event + # Returns the line number of the event. def lineno Primitive.tracepoint_attr_lineno end - # Path of the file being run + # Returns the path of the file being executed. def path Primitive.tracepoint_attr_path end - # Return the parameters definition of the method or block that the - # current hook belongs to. Format is the same as for Method#parameters + # Returns the parameter definitions of the method or block that the + # current hook belongs to. The format is the same as for Method#parameters. def parameters Primitive.tracepoint_attr_parameters end - # Return the name at the definition of the method being called + # Returns the name at the definition of the method being called. def method_id Primitive.tracepoint_attr_method_id end - # Return the called name of the method being called + # Returns the called name of the method being called. def callee_id Primitive.tracepoint_attr_callee_id end - # Return class or module of the method being called. + # Returns the class or module of the method being called. # - # class C; def foo; end; end - # trace = TracePoint.new(:call) do |tp| - # p tp.defined_class #=> C - # end.enable do - # C.new.foo - # end + # class C; def foo; end; end + # trace = TracePoint.new(:call) do |tp| + # p tp.defined_class #=> C + # end.enable do + # C.new.foo + # end # - # If method is defined by a module, then that module is returned. + # If the method is defined by a module, then that module is returned. # - # module M; def foo; end; end - # class C; include M; end; - # trace = TracePoint.new(:call) do |tp| - # p tp.defined_class #=> M - # end.enable do - # C.new.foo - # end + # module M; def foo; end; end + # class C; include M; end + # trace = TracePoint.new(:call) do |tp| + # p tp.defined_class #=> M + # end.enable do + # C.new.foo + # end # - # Note: #defined_class returns singleton class. + # Note: #defined_class returns the singleton class. # - # 6th block parameter of Kernel#set_trace_func passes original class - # of attached by singleton class. + # The 6th block parameter of Kernel#set_trace_func passes the original class + # attached by the singleton class. # # This is a difference between Kernel#set_trace_func and TracePoint. # - # class C; def self.foo; end; end - # trace = TracePoint.new(:call) do |tp| - # p tp.defined_class #=> # - # end.enable do - # C.foo - # end + # class C; def self.foo; end; end + # trace = TracePoint.new(:call) do |tp| + # p tp.defined_class #=> # + # end.enable do + # C.foo + # end def defined_class Primitive.tracepoint_attr_defined_class end - # Return the generated binding object from event. + # Returns the generated binding object from the event. # - # Note that for +:c_call+ and +:c_return+ events, the method will return + # Note that for +:c_call+ and +:c_return+ events, the method returns # +nil+, since C methods themselves do not have bindings. def binding Primitive.tracepoint_attr_binding end - # Return the trace object during event + # Returns the trace object during the event. # - # Same as the following, except it returns the correct object (the method + # Similar to the following, but it returns the correct object (the method # receiver) for +:c_call+ and +:c_return+ events: # # trace.binding.eval('self') @@ -397,26 +392,26 @@ class TracePoint Primitive.tracepoint_attr_self end - # Return value from +:return+, +:c_return+, and +:b_return+ event + # Returns the return value from +:return+, +:c_return+, and +:b_return+ events. def return_value Primitive.tracepoint_attr_return_value end - # Value from exception raised on the +:raise+ event, or rescued on the +:rescue+ event. + # Returns the exception raised on the +:raise+ event or rescued on the +:rescue+ event. def raised_exception Primitive.tracepoint_attr_raised_exception end - # Compiled source code (String) on *eval methods on the +:script_compiled+ event. - # If loaded from a file, it will return nil. + # Returns the compiled source code (String) from eval methods on the +:script_compiled+ event. + # If loaded from a file, it returns +nil+. def eval_script Primitive.tracepoint_attr_eval_script end - # Compiled instruction sequence represented by a RubyVM::InstructionSequence instance + # Returns the compiled instruction sequence represented by a RubyVM::InstructionSequence instance # on the +:script_compiled+ event. # - # Note that this method is MRI specific. + # Note that this method is CRuby-specific. def instruction_sequence Primitive.tracepoint_attr_instruction_sequence end