Actions
Bug #9551
closed
[DOC] Fix for documentation of Kernel::catch
Description
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
Updated by 
Updated by
Actions
Like0
Like0Like0