[ruby-core:60964] [ruby-trunk - Bug #9551] [Open] [DOC] Fix for documentation of Kernel::catch

Issue #9551 has been reported by Jesse Sielaff.

----------------------------------------
Bug #9551: [DOC] Fix for documentation of Kernel::catch
https://bugs.ruby-lang.org/issues/9551

* Author: Jesse Sielaff
* Status: Open
* Priority: Normal
* Assignee: 
* Category: 
* Target version: 
* ruby -v: 2.1.0
* Backport: 1.9.3: UNKNOWN, 2.0.0: UNKNOWN, 2.1: UNKNOWN
----------------------------------------
The current documentation for `Kernel::catch` contains complicated examples and confusing language.
*"when arg is given, catch yields it as is, or when no arg is given, catch assigns a new unique object to throw. this is useful for nested catch."*

This patch improves the explanation of how `catch` and `throw` work together and gives clear, very simple code examples.

The unified diff patch is attached. Full text of the new documentation block is below.
    
    /*
     *  call-seq:
     *     catch([tag]) {|tag| block }  -> obj
     *
     *  +catch+ executes its block. If +throw+ is not called,
     *  the block executes normally, and +catch+ returns the
     *  value of the last expression evaluated.
     *
     *     catch(1) { 123 }            # => 123
     *
     *  If +throw(tag2, val)+ is called, Ruby searches up its
     *  stack for a +catch+ block whose _tag_ has the same
     *  +object_id+ as _tag2_. If found, the block stops
     *  executing and returns _val_ (or +nil+ if no second
     *  argument was given to +throw+).
     *
     *     catch(1) { throw(1, 456) }  # => 456
     *     catch(1) { throw(1) }       # => nil
     *
     *  When _tag_ is passed as the first argument, +catch+
     *  yields it as the parameter of the block.
     *
     *     catch(1) {|x| x + 2 }       # => 3
     *
     *  When no _tag_ is given, +catch+ yields a new unique
     *  object (as from +Object.new+) as the block parameter.
     *  This object can then be used as the argument to
     *  +throw+, and will match the correct +catch+ block.
     *
     *     catch do |obj_A|
     *       catch do |obj_B|
     *         throw(obj_B, 123)
     *         puts "This puts is not reached"
     *       end
     *
     *       puts "This puts is displayed"
     *       456
     *     end
     *
     *     # => 456
     *
     *     catch do |obj_A|
     *       catch do |obj_B|
     *         throw(obj_A, 123)
     *         puts "This puts is still not reached"
     *       end
     *
     *       puts "Now this puts is also not reached"
     *       456
     *     end
     *
     *     # => 123
     */


---Files--------------------------------
ruby-changes.patch (2.61 KB)


-- 
http://bugs.ruby-lang.org/