ruby-changes:67723
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:00:59 +0900 (JST)
Subject: [ruby-changes:67723] 1b6245ccdc (master): include/ruby/internal/error.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=1b6245ccdc From 1b6245ccdcd414698a257847d508603f438578ca 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: Mon, 21 Dec 2020 11:15:08 +0900 Subject: include/ruby/internal/error.h: add doxygen Must not be a bad idea to improve documents. --- error.c | 2 +- eval.c | 14 -- include/ruby/internal/error.h | 557 +++++++++++++++++++++++++++++++++++++++--- 3 files changed, 528 insertions(+), 45 deletions(-) diff --git a/error.c b/error.c index 79a24a7..6cd64bc 100644 --- a/error.c +++ b/error.c @@ -45,7 +45,7 @@ https://github.com/ruby/ruby/blob/trunk/error.c#L45 #include "builtin.h" /*! - * \defgroup exception Exception handlings + * \addtogroup exception * \{ */ diff --git a/eval.c b/eval.c index ff05984..209ad33 100644 --- a/eval.c +++ b/eval.c @@ -1769,26 +1769,12 @@ errinfo_getter(ID id, VALUE *_) https://github.com/ruby/ruby/blob/trunk/eval.c#L1769 return get_errinfo(); } -/*! The current exception in the current thread. - * - * Same as \c $! in Ruby. - * \return the current exception or \c Qnil - * \ingroup exception - */ VALUE rb_errinfo(void) { return GET_EC()->errinfo; } -/*! Sets the current exception (\c $!) to the given value - * - * \param[in] err an \c Exception object or \c Qnil. - * \exception TypeError if \a err is neither an exception nor \c nil. - * \note this function does not raise the exception. - * Use \c rb_raise() when you want to raise. - * \ingroup exception - */ void rb_set_errinfo(VALUE err) { diff --git a/include/ruby/internal/error.h b/include/ruby/internal/error.h index 9f41119..6b54f56 100644 --- a/include/ruby/internal/error.h +++ b/include/ruby/internal/error.h @@ -20,64 +20,561 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/error.h#L20 * extension libraries. They could be written in C++98. * @brief Declares ::rb_raise(). */ +#include "ruby/internal/attr/cold.h" +#include "ruby/internal/attr/format.h" +#include "ruby/internal/attr/noreturn.h" +#include "ruby/internal/attr/nonnull.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" -#include "ruby/backward/2/attributes.h" + +/** + * @defgroup exception Exception handlings + * @{ + */ RBIMPL_SYMBOL_EXPORT_BEGIN() +/** + * This is the same as `$!` in Ruby. + * + * @retval RUBY_Qnil Not handling exceptions at the moment. + * @retval otherwise The current exception in the current thread. + * @ingroup exception + */ VALUE rb_errinfo(void); + +/** + * Sets the current exception (`$!`) to the given value. + * + * @exception rb_eTypeError What is given was neither ::rb_eException nor + * ::RUBY_Qnil. + * @note Use rb_raise() instead to raise `err`. This function just + * assigns the given object to the global variable. + * @ingroup exception + */ void rb_set_errinfo(VALUE); +/** + * Warning categories. A warning issued using this API can be selectively + * requested / suppressed by the end-users. For instance passing + * `-W:no-deprecated` to the ruby process would suppress those warnings in + * deprecated category. + * + * @warning There is no way to declare a new category (for now). + */ typedef enum { + /** Category unspecified. */ RB_WARN_CATEGORY_NONE, + + /** Warning is for deprecated features. */ RB_WARN_CATEGORY_DEPRECATED, + + /** Warning is for experimental features. */ RB_WARN_CATEGORY_EXPERIMENTAL, + RB_WARN_CATEGORY_ALL_BITS = 0x6 /* no RB_WARN_CATEGORY_NONE bit */ } rb_warning_category_t; -/* for rb_readwrite_sys_fail first argument */ +/** for rb_readwrite_sys_fail first argument */ enum rb_io_wait_readwrite {RB_IO_WAIT_READABLE, RB_IO_WAIT_WRITABLE}; +/** @cond INTERNAL_MACRO */ #define RB_IO_WAIT_READABLE RB_IO_WAIT_READABLE #define RB_IO_WAIT_WRITABLE RB_IO_WAIT_WRITABLE +/** @endcond */ + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL((2)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 2, 3) +/** + * Exception entry point. By calling this function the execution of your + * program gets interrupted to "raise" an exception up to the callee entities. + * Programs could "rescue" that exception, or could "ensure" some part of them. + * If nobody cares about such things, the raised exception reaches at the top + * of execution. This yields abnormal end of the process. + * + * @param[in] exc A subclass of ::rb_eException. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + * @exception exc The specified exception. + * @note It never returns. + */ +void rb_raise(VALUE exc, const char *fmt, ...); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL((1)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) +/** + * Raises the unsung "fatal" exception. This is considered severe. Nobody can + * rescue the exception. Once raised, process termination is inevitable. + * However ensure clauses still run, so that resources are properly cleaned up. + * + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + * @exception rb_eFatal An exception that you cannot rescue. + * @note It never returns. + */ +void rb_fatal(const char *fmt, ...); + +RBIMPL_ATTR_COLD() +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL((1)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) +/** + * Interpreter panic switch. Immediate process termination without any + * synchronisations shall occur. LOTS of internal states, stack traces, and + * even machine registers are displayed if possible for debugging purposes + * then. + * + * @warning Do not use this API. + * @warning You are not expected to use this API. + * @warning Why not just fix your code instead of calling this API? + * @warning It was a bad idea to expose this API to extension libraries at + * the first place. We just cannot delete it at this point for + * backwards compatibility. That doesn't mean everyone are + * welcomed to call this function at will. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + * @note It never returns. + */ +void rb_bug(const char *fmt, ...); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL(()) +/** + * This is a wrapper of rb_bug() which automatically constructs appropriate + * message from the passed errno. + * + * @param[in] msg Additional message to display. + * @exception err C level errno. + * @note It never returns. + */ +void rb_bug_errno(const char *msg, int err); + +RBIMPL_ATTR_NORETURN() +/** + * Converts a C errno into a Ruby exception, then raises it. For instance: + * + * ```C + * static VALUE + * foo(VALUE argv) + * { + * const auto cmd = StringValueCStr(argv); + * const auto waitr = system(cmd); + * if (waitr == -1) { + * rb_sys_fail("system(3posix)"); // <-------------- this + * } + * else { + * return INT2FIX(fd); + * } + * } + * ``` + * + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing errno. + * @note It never returns. + */ +void rb_sys_fail(const char *msg); + +RBIMPL_ATTR_NORETURN() +/** + * Identical to rb_sys_fail(), except it takes the message in Ruby's String + * instead of C's. + * + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing errno. + * @note It never returns. + */ +void rb_sys_fail_str(VALUE msg); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL((2)) +/** + * Identical to rb_sys_fail(), except it takes additional module to extend the + * exception object before raising. + * + * @param[in] mod A ::rb_cModule instance. + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing errno. + * @note It never returns. + * + * @internal + * + * Does anybody use it? + */ +void rb_mod_sys_fail(VALUE mod, const char *msg); + +RBIMPL_ATTR_NORETURN() +/** + * Identical to rb_mod_sys_fail(), except it takes the message in Ruby's String + * instead of C's. + * + * @param[in] mod A ::rb_cModule instance. + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing errno. + * @note It never returns. + */ +void rb_mod_sys_fail_str(VALUE mod, VALUE msg); + +RBIMPL_ATTR_NORETURN() +/** + * Raises appropriate exception using the parameters. + * + * In Ruby level there are rb_eEAGAINWaitReadable etc. This function maps the + * given parameter to an appropriate exception class, then raises it. + * + * @param[in] waiting Reason for the IO to wait. + * @param[in] msg Additional message to raise. + * @exception rb_eEAGAINWaitWritable + * @exception rb_eEWOULDBLOCKWaitWritable + * @exception rb_eEINPROGRESSWaitWritable + * @exception rb_eEAGAINWaitReadable + * @exception rb_eEWOULDBLOCKWaitReadable + * @exception rb_eEINPROGRESSWaitReadable + * @exception rb_eSystemCallError + * @note It never returns. + */ +void rb_readwrite_sys_fail(enum rb_io_wait_readwrite waiting, const char *msg); + +RBIMPL_ATTR_NORETURN() +/** + * Breaks from a block. Because you are using a CAPI this is not as intuitive + * as it sounds. In order for this function to properly work, make a + * ::rb_block_call_func_t function that calls it internally, and pass that + * function to rb_block_call(). + * + * @exception rb_eLocalJumpError Called from outside of a block. + * @note It never returns. + */ +void rb_iter_break(void); + +RBIMPL_ATTR_NORETURN() +/** + * Identical to rb_iter_break(), except it additionally takes the "value" of + * this breakage. It will be the evaluation result of the iterator. This is + * kind of complicated; yo (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/