Add file.c comments (and necessary support in parse_c.rb)

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

1 files changed, 78 insertions, 0 deletions

diff --git a/eval.c b/eval.c
index 6369df8025..10d52d6511 100644
--- a/eval.c
+++ b/eval.c
@@ -10134,8 +10134,70 @@ rb_thread_atfork()
     curr_thread->prev = curr_thread;
 }
 
+
+/*
+ *  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).
+ *     
+ *  For instance:
+ *     
+ *     arr = [ "Freddie", "Herbie", "Ron", "Max", "Ringo" ]
+ *     callcc{|$cc|}
+ *     puts(message = arr.shift)
+ *     $cc.call unless message =~ /Max/
+ *     
+ *  <em>produces:</em>
+ *     
+ *     Freddie
+ *     Herbie
+ *     Ron
+ *     Max
+ *     
+ *  This (somewhat contrived) example allows the inner loop to abandon
+ *  processing early:
+ *     
+ *     callcc {|cont|
+ *       for i in 0..4
+ *         print "\n#{i}: "
+ *         for j in i*5...(i+1)*5
+ *           cont.call() if j == 17
+ *           printf "%3d", j
+ *         end
+ *       end
+ *     }
+ *     print "\n"
+ *     
+ *  <em>produces:</em>
+ *     
+ *     0:   0  1  2  3  4
+ *     1:   5  6  7  8  9
+ *     2:  10 11 12 13 14
+ *     3:  15 16
+ */
+
 static VALUE rb_cCont;
 
+/*
+ *  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.
+ */
+
 static VALUE
 rb_callcc(self)
     VALUE self;
@@ -10169,6 +10231,22 @@ rb_callcc(self)
     }
 }
 
+/*
+ *  call-seq:
+ *     cont.call(args, ...) 
+ *     cont[args, ...]
+ *  
+ *  Invokes the continuation. The program continues from the end of the
+ *  <code>callcc</code> block. If no arguments are given, the original
+ *  <code>callcc</code> returns <code>nil</code>. If one argument is
+ *  given, <code>callcc</code> returns it. Otherwise, an array
+ *  containing <i>args</i> is returned.
+ *     
+ *     callcc {|cont|  cont.call }           #=> nil
+ *     callcc {|cont|  cont.call 1 }         #=> 1
+ *     callcc {|cont|  cont.call 1, 2, 3 }   #=> [1, 2, 3]
+ */
+
 static VALUE
 rb_cont_call(argc, argv, cont)
     int argc;