* cont.c: apply documentation patch by Run Paint Run Run.

  [ruby-core:32915]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@29604 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 28 insertions, 21 deletions

diff --git a/cont.c b/cont.c
index 48ae896405..b0b3f41c7d 100644
--- a/cont.c
+++ b/cont.c
@@ -752,18 +752,19 @@ cont_restore_0(rb_context_t *cont, VALUE *addr_in_prev_frame)
 /*
  *  Document-class: Continuation
  *
- *  Continuation objects are generated by
- *  <code>Kernel#callcc</code>. They hold a return address and execution
- *  context, allowing a nonlocal return to the end of the
- *  <code>callcc</code> block from anywhere within a program.
- *  Continuations are somewhat analogous to a structured version of C's
- *  <code>setjmp/longjmp</code> (although they contain more state, so
- *  you might consider them closer to threads).
+ *  Continuation objects are generated by <code>Kernel#callcc</code>,
+ *  after having <code>require</code>d <i>continuation</i>. They hold
+ *  a return address and execution context, allowing a nonlocal return
+ *  to the end of the <code>callcc</code> block from anywhere within a
+ *  program.  Continuations are somewhat analogous to a structured
+ *  version of C's <code>setjmp/longjmp</code> (although they contain
+ *  more state, so you might consider them closer to threads).
  *
  *  For instance:
  *
+ *     require "continuation"
  *     arr = [ "Freddie", "Herbie", "Ron", "Max", "Ringo" ]
- *     callcc{|$cc|}
+ *     callcc{|cc| $cc = cc}
  *     puts(message = arr.shift)
  *     $cc.call unless message =~ /Max/
  *
@@ -777,6 +778,7 @@ cont_restore_0(rb_context_t *cont, VALUE *addr_in_prev_frame)
  *  This (somewhat contrived) example allows the inner loop to abandon
  *  processing early:
  *
+ *     require "continuation"
  *     callcc {|cont|
  *       for i in 0..4
  *         print "\n#{i}: "
@@ -786,7 +788,7 @@ cont_restore_0(rb_context_t *cont, VALUE *addr_in_prev_frame)
  *         end
  *       end
  *     }
- *     print "\n"
+ *     puts
  *
  *  <em>produces:</em>
  *
@@ -800,14 +802,16 @@ cont_restore_0(rb_context_t *cont, VALUE *addr_in_prev_frame)
  *  call-seq:
  *     callcc {|cont| block }   ->  obj
  *
- *  Generates a <code>Continuation</code> object, which it passes to the
- *  associated block. Performing a <em>cont</em><code>.call</code> will
- *  cause the <code>callcc</code> to return (as will falling through the
- *  end of the block). The value returned by the <code>callcc</code> is
- *  the value of the block, or the value passed to
- *  <em>cont</em><code>.call</code>. See class <code>Continuation</code>
- *  for more details. Also see <code>Kernel::throw</code> for
- *  an alternative mechanism for unwinding a call stack.
+ *  Generates a <code>Continuation</code> object, which it passes to
+ *  the associated block. You need to <code>require
+ *  'continuation'</code> before using this method. Performing a
+ *  <em>cont</em><code>.call</code> will cause the <code>callcc</code>
+ *  to return (as will falling through the end of the block). The
+ *  value returned by the <code>callcc</code> is the value of the
+ *  block, or the value passed to <em>cont</em><code>.call</code>. See
+ *  class <code>Continuation</code> for more details. Also see
+ *  <code>Kernel::throw</code> for an alternative mechanism for
+ *  unwinding a call stack.
  */
 
 static VALUE
@@ -1305,9 +1309,10 @@ rb_fiber_yield(int argc, VALUE *argv)
  *  call-seq:
  *     fiber.alive? -> true or false
  *
- *  Returns true if the fiber can still be resumed (or transferred to).
- *  After finishing execution of the fiber block this method will always
- *  return false.
+ *  Returns true if the fiber can still be resumed (or transferred
+ *  to). After finishing execution of the fiber block this method will
+ *  always return false. You need to <code>require 'fiber'</code>
+ *  before using this method.
  */
 VALUE
 rb_fiber_alive_p(VALUE fibval)
@@ -1344,7 +1349,9 @@ rb_fiber_m_resume(int argc, VALUE *argv, VALUE fib)
  *
  *  Transfer control to another fiber, resuming it from where it last
  *  stopped or starting it if it was not resumed before. The calling
- *  fiber will be suspended much like in a call to <code>Fiber.yield</code>.
+ *  fiber will be suspended much like in a call to
+ *  <code>Fiber.yield</code>. You need to <code>require 'fiber'</code>
+ *  before using this method.
  *
  *  The fiber which receives the transfer call is treats it much like
  *  a resume call. Arguments passed to transfer are treated like those