k0kubun	2018-11-12 09:55:34 +0900 (Mon, 12 Nov 2018)

  New Revision: 65674

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

  Log:
    Document binding.irb on Binding [ci skip]
    
    For some reason this very useful method was undocumented since it was added in
    493e48897421d176a8faf0f0820323d79ecdf94a which makes finding it in the docs
    impossible before this change.
    
    I've added a detailed example with sample code because it's one of the most
    powerful tools to debug Ruby code and I believe very few people are aware of it
    due to the lack of documentation.
    
    [Fix GH-2010]
    
    From: Olivier Lacan <hi@o...>

  Modified files:
    trunk/lib/irb.rb
Index: lib/irb.rb
===================================================================
--- lib/irb.rb	(revision 65673)
+++ lib/irb.rb	(revision 65674)
@@ -733,7 +733,63 @@ module IRB https://github.com/ruby/ruby/blob/trunk/lib/irb.rb#L733
 end
 
 class Binding
-  # :nodoc:
+  # Opens an IRB session where `binding.irb` is called which allows for
+  # interactive debugging. You can call any methods or variables available in
+  # the current scope, and mutate state if you need to.
+  #
+  #
+  # Given a Ruby file called `potato.rb` containing the following code:
+  #
+  #     class Potato
+  #       def initialize
+  #         @cooked = false
+  #         binding.irb
+  #         puts @cooked
+  #       end
+  #     end
+  #
+  #     Potato.new
+  #
+  # Running `ruby potato.rb` will open an IRB session where `binding.irb` is
+  # called, and you will see the following:
+  #
+  #     $ ruby potato.rb
+  #
+  #     From: potato.rb @ line 3 :
+  #
+  #         1: class Potato
+  #         2:   def initialize
+  #         3:     @cooked = false
+  #      => 4:     binding.irb
+  #         5:     puts "Cooked potato: #{@cooked}"
+  #         6:   end
+  #         7: end
+  #         8:
+  #         9: Potato.new
+  #
+  #     irb(#<Potato:0x00007feea1916670>):001:0>
+  #
+  # You can type any valid Ruby code and it will be evaluated in the current
+  # context. This allows you to debug without having to run your code repeatedly:
+  #
+  #     irb(#<Potato:0x00007feea1916670>):001:0> @cooked
+  #     => false
+  #     irb(#<Potato:0x00007feea1916670>):002:0> self.class
+  #     => Potato
+  #     irb(#<Potato:0x00007feea1916670>):003:0> caller.first
+  #     => ".../2.5.1/lib/ruby/2.5.0/irb/workspace.rb:85:in `eval'"
+  #     irb(#<Potato:0x00007feea1916670>):004:0> @cooked = true
+  #     => true
+  #
+  # You can exit the IRB session with the `exit` command. Note that exiting will
+  # resume execution where +binding.call+ had paused it, as you can see from the
+  # output printed to standard output in this example:
+  #
+  #     irb(#<Potato:0x00007feea1916670>):005:0> exit
+  #     $ Cooked potato: true
+  #
+  #
+  # See IRB@IRB+Usage for more information.
   def irb
     IRB.setup(eval("__FILE__"), argv: [])
     workspace = IRB::WorkSpace.new(self)

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