Bug #9551: [DOC] Fix for documentation of Kernel::catch

• Status: Closed
• Assignee: zzak (zzak _)
• Target version: -
• ruby -v: 2.1.0
• Backport: 1.9.3: UNKNOWN, 2.0.0: UNKNOWN, 2.1: UNKNOWN

[jessesielaff (Jesse Sielaff)]

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
 */

[nagachika (Tomoyuki Chikanaga)]

• Category set to doc
• Status changed from Open to Assigned
• Assignee set to zzak (zzak _)

[zzak (zzak _)]

• Status changed from Assigned to Closed
• % Done changed from 0 to 100

Applied in changeset r46985.

---

• vm_eval.c: [DOC] [Bug #9551] Improve clarity of Kernel::catch
  documentation, patch by Jesse Sielaff.