Merge pull request #5856 from dearblue/doc/fiber-funcs

Updates documentation for `mrb_fiber_resume()` and `mrb_fiber_yield()`

include/mruby.h

@@ -1460,6 +1460,10 @@ MRB_API mrb_bool mrb_func_basic_p(mrb_state *mrb, mrb_value obj, mrb_sym mid, mr
  * Resume a Fiber
  *
  * Implemented in mruby-fiber
+ *
+ * Switches to the specified fiber and executes. Like the `Fiber#resume` method.
+ *
+ * @note It can only be called before entering the mruby VM (e.g. in the `main()` function).
  */
 MRB_API mrb_value mrb_fiber_resume(mrb_state *mrb, mrb_value fib, mrb_int argc, const mrb_value *argv);
 
@@ -1467,6 +1471,15 @@ MRB_API mrb_value mrb_fiber_resume(mrb_state *mrb, mrb_value fib, mrb_int argc,
  * Yield a Fiber
  *
  * Implemented in mruby-fiber
+ *
+ * Passes control to the caller fiber of the running fiber. Like the `Fiber.yield` method.
+ *
+ * @note This function is only available from inside a function defined as a method by,
+ *       for example, `mrb_define_method()`.
+ *       Also, the work following `mrb_fiber_yield()` cannot be performed,
+ *       and the return value of `mrb_fiber_yield()` must be returned as is.
+ *
+ *           return mrb_fiber_yield(mrb, argc, argv);
  */
 MRB_API mrb_value mrb_fiber_yield(mrb_state *mrb, mrb_int argc, const mrb_value *argv);
 

mrbgems/mruby-fiber/src/fiber.c

@@ -259,6 +259,9 @@ fiber_switch(mrb_state *mrb, mrb_value self, mrb_int len, const mrb_value *a, mr
  *  to the next <code>Fiber.yield</code> statement inside the fiber's block
  *  or to the block value if it runs to completion without any
  *  <code>Fiber.yield</code>
+ *
+ *  This method cannot be called from C using <code>mrb_funcall()</code>.
+ *  Use <code>mrb_fiber_resume()</code> function instead.
  */
 static mrb_value
 fiber_resume(mrb_state *mrb, mrb_value self)
@@ -275,7 +278,6 @@ fiber_resume(mrb_state *mrb, mrb_value self)
   return fiber_switch(mrb, self, len, a, TRUE, vmexec);
 }
 
-/* resume thread with given arguments */
 MRB_API mrb_value
 mrb_fiber_resume(mrb_state *mrb, mrb_value fib, mrb_int len, const mrb_value *a)
 {
@@ -344,8 +346,6 @@ fiber_transfer(mrb_state *mrb, mrb_value self)
   return fiber_switch(mrb, self, len, a, FALSE, FALSE);
 }
 
-/* yield values to the caller fiber */
-/* mrb_fiber_yield() must be called as `return mrb_fiber_yield(...)` */
 MRB_API mrb_value
 mrb_fiber_yield(mrb_state *mrb, mrb_int len, const mrb_value *a)
 {
@@ -380,6 +380,9 @@ mrb_fiber_yield(mrb_state *mrb, mrb_int len, const mrb_value *a)
  *
  *  mruby limitation: Fiber resume/yield cannot cross C function boundary.
  *  thus you cannot yield from #initialize which is called by mrb_funcall().
+ *
+ *  This method cannot be called from C using <code>mrb_funcall()</code>.
+ *  Use <code>mrb_fiber_yield()</code> function instead.
  */
 static mrb_value
 fiber_yield(mrb_state *mrb, mrb_value self)