Project

General

Profile

Actions

Bug #9551

closed

[DOC] Fix for documentation of Kernel::catch

Added by jessesielaff (Jesse Sielaff) about 10 years ago. Updated over 9 years ago.

Status:
Closed
Assignee:
Target version:
-
[ruby-core:60964]

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

ruby-changes.patch (2.61 KB) ruby-changes.patch unified diff patch jessesielaff (Jesse Sielaff), 02/22/2014 03:39 AM

Updated by nagachika (Tomoyuki Chikanaga) about 10 years ago

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

Updated by zzak (zzak _) over 9 years ago

  • 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.
Actions

Also available in: Atom PDF

Like0
Like0Like0