https://git.ruby-lang.org/ruby.git/commit/?id=90f2ab9d62

From 90f2ab9d62860d7b3413fb363403c1d16b4a860e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?=
 <shyouhei@r...>
Date: Thu, 30 Sep 2021 13:26:56 +0900
Subject: rb_fiber_raise(): add doxygen

Must not be a bad idea to improve documents.
---
 cont.c                              |  4 ++--
 include/ruby/internal/intern/cont.h | 32 +++++++++++++++++++++++---------
 2 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/cont.c b/cont.c
index b947c61003..8a56fa6735 100644
--- a/cont.c
+++ b/cont.c
@@ -2702,7 +2702,7 @@ rb_fiber_s_yield(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/cont.c#L2702
 }
 
 static VALUE
-fiber_raise(rb_fiber_t *fiber, int argc, VALUE *argv)
+fiber_raise(rb_fiber_t *fiber, int argc, const VALUE *argv)
 {
     VALUE exception = rb_make_exception(argc, argv);
 
@@ -2718,7 +2718,7 @@ fiber_raise(rb_fiber_t *fiber, int argc, VALUE *argv) https://github.com/ruby/ruby/blob/trunk/cont.c#L2718
 }
 
 VALUE
-rb_fiber_raise(VALUE fiber, int argc, VALUE *argv)
+rb_fiber_raise(VALUE fiber, int argc, const VALUE *argv)
 {
     return fiber_raise(fiber_ptr(fiber), argc, argv);
 }
diff --git a/include/ruby/internal/intern/cont.h b/include/ruby/internal/intern/cont.h
index b0d9137dd9..37493009f5 100644
--- a/include/ruby/internal/intern/cont.h
+++ b/include/ruby/internal/intern/cont.h
@@ -139,8 +139,7 @@ VALUE rb_fiber_resume_kw(VALUE fiber, int argc, const VALUE *argv, int kw_splat) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/cont.h#L139
  * fiber then suspends its execution until next time it is resumed.
  *
  * This function can  also raise arbitrary exceptions injected  from outside of
- * the fiber, using `Fiber#raise`  Ruby level API.  There is no  way to do that
- * from C though.
+ * the fiber using rb_fiber_raise().
  *
  * ```ruby
  * exc = Class.new Exception
@@ -159,12 +158,6 @@ VALUE rb_fiber_resume_kw(VALUE fiber, int argc, const VALUE *argv, int kw_splat) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/cont.h#L158
  * @param[in]  argv           Passed to rb_fiber_resume().
  * @exception  rb_eException  (See above)
  * @return     (See rb_fiber_resume() for details)
- *
- * @internal
- *
- * "There is no way  to do that from C" is a lie.   But @shyouhei doesn't think
- * this very intentionally obfuscated way  to raise arbitrary exceptions from C
- * is an official C API.  Extension libraries must not know this fact.
  */
 VALUE rb_fiber_yield(int argc, const VALUE *argv);
 
@@ -239,7 +232,28 @@ VALUE rb_fiber_transfer(VALUE fiber, int argc, const VALUE *argv); https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/cont.h#L232
  */
 VALUE rb_fiber_transfer_kw(VALUE fiber, int argc, const VALUE *argv, int kw_splat);
 
-VALUE rb_fiber_raise(VALUE fiber, int argc, VALUE *argv);
+/**
+ * Identical to rb_fiber_resume()  but instead of resuming  normal execution of
+ * the passed fiber, it  raises the given exception in it.   From inside of the
+ * fiber this would be seen as if rb_fiber_yield() raised.
+ *
+ * This function  does return in case  the passed fiber gracefully  handled the
+ * passed exception.  But  if it does not, the raised  exception propagates out
+ * of the passed fiber; this function then does not return.
+ *
+ * Parameters are passed to rb_make_exception()  to create an exception object.
+ * See its document for what are allowed here.
+ *
+ * It is  a failure to  call this function against  a fiber which  is resuming,
+ * have never run yet, or has already finished running.
+ *
+ * @param[out]  fiber           Where exception is raised.
+ * @param[in]   argc            Passed as-is to rb_make_exception().
+ * @param[in]   argv            Passed as-is to rb_make_exception().
+ * @exception   rb_eFiberError  `fiber` is terminated etc.
+ * @return      (See rb_fiber_resume() for details)
+ */
+VALUE rb_fiber_raise(VALUE fiber, int argc, const VALUE *argv);
 
 RBIMPL_SYMBOL_EXPORT_END()
 
-- 
cgit v1.2.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/