Updates documentation for `mrb_fiber_resume()` and `mrb_fiber_yield()`
Added note on `mrb_fiber_resume()` and `mrb_fiber_yield()`.
Removed comments from C files that were not documented by yard and doxygen instead.
Leads to use of `mrb_fiber_resume()` instead of `Fiber#resume` in C.
Leads to use of `mrb_fiber_yield()` instead of `Fiber.yield` in C.
MODIFY
include/mruby.h
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);

MODIFY
mrbgems/mruby-fiber/src/fiber.c
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)

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

- Added note on `mrb_fiber_resume()` and `mrb_fiber_yield()`.
  Removed comments from C files that were not documented by yard and doxygen instead.
- Leads to use of `mrb_fiber_resume()` instead of `Fiber#resume` in C.
- Leads to use of `mrb_fiber_yield()` instead of `Fiber.yield` in C.