summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2014-07-27 21:35:47 +0000
committerzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2014-07-27 21:35:47 +0000
commit60272f90fd9b863be17455248f75a728cf08c3be (patch)
treee980ebfa2935d7f617d5fd0f97f47beb0bdecfda
parent747243cc0e35a34cd48c12fed6b7d4430cd68997 (diff)
* vm_eval.c: [DOC] [Bug #9551] Improve clarity of Kernel::catch
documentation, patch by Jesse Sielaff. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@46985 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r--ChangeLog5
-rw-r--r--vm_eval.c67
2 files changed, 47 insertions, 25 deletions
diff --git a/ChangeLog b/ChangeLog
index 6445c041223..b0f30b63159 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Mon Jul 28 06:34:43 2014 Zachary Scott <e@zzak.io>
+
+ * vm_eval.c: [DOC] [Bug #9551] Improve clarity of Kernel::catch
+ documentation, patch by Jesse Sielaff.
+
Mon Jul 28 06:24:54 2014 Zachary Scott <e@zzak.io>
* lib/uri/common.rb: [DOC] [Bug #9563] Recommend using URI.escape
diff --git a/vm_eval.c b/vm_eval.c
index a67c75cb6d3..95edb932735 100644
--- a/vm_eval.c
+++ b/vm_eval.c
@@ -1780,39 +1780,56 @@ catch_i(VALUE tag, VALUE data)
/*
* call-seq:
- * catch([arg]) {|tag| block } -> obj
+ * catch([tag]) {|tag| block } -> obj
*
- * +catch+ executes its block. If a +throw+ is
- * executed, Ruby searches up its stack for a +catch+ block
- * with a tag corresponding to the +throw+'s
- * _tag_. If found, that block is terminated, and
- * +catch+ returns the value given to +throw+. If
- * +throw+ is not called, the block terminates normally, and
- * the value of +catch+ is the value of the last expression
- * evaluated. +catch+ expressions may be nested, and the
- * +throw+ call need not be in lexical scope.
+ * +catch+ executes its block. If +throw+ is not called,
+ * the block executes normally, and +catch+ returns the
+ * value of the last expression evaluated.
*
- * def routine(n)
- * puts n
- * throw :done if n <= 0
- * routine(n-1)
- * end
+ * 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(:done) { routine(3) }
+ * catch(1) { throw(1, 456) } # => 456
+ * catch(1) { throw(1) } # => nil
*
- * <em>produces:</em>
+ * When _tag_ is passed as the first argument, +catch+
+ * yields it as the parameter of the block.
+ *
+ * catch(1) {|x| x + 2 } # => 3
*
- * 3
- * 2
- * 1
- * 0
+ * 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.
*
- * 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+. _arg_ can
- * be an arbitrary object, not only Symbol.
+ * 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
*/
static VALUE