Document binding.irb on Binding [ci skip]

For some reason this very useful method was undocumented since it was added in
493e488974 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@olivierlacan.com>

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

lib/irb.rb

@@ -733,7 +733,63 @@ module IRB
 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)