include/ruby/internal/intern/eval.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]

eval.c

@@ -683,10 +683,6 @@ rb_exc_fatal(VALUE mesg)
     rb_exc_exception(mesg, TAG_FATAL, Qnil);
 }
 
-/*!
- * Raises an \c Interrupt exception.
- * \ingroup exception
- */
 void
 rb_interrupt(void)
 {
@@ -814,26 +810,6 @@ make_exception(int argc, const VALUE *argv, int isstr)
     return mesg;
 }
 
-/*!
- * Make an \c Exception object from the list of arguments in a manner
- * similar to \c Kernel\#raise.
- *
- * \param[in] argc the number of arguments
- * \param[in] argv a pointer to the array of arguments.
- *
- * The first form of this function takes a \c String argument. Then
- * it returns a \c RuntimeError whose error message is the given value.
- *
- * The second from of this function takes an \c Exception object. Then
- * it just returns the given value.
- *
- * The last form takes an exception class, an optional error message and
- * an optional array of backtrace. Then it passes the optional arguments
- * to \c #exception method of the exception class.
- *
- * \return the exception object, or \c Qnil if \c argc is 0.
- * \ingroup exception
- */
 VALUE
 rb_make_exception(int argc, const VALUE *argv)
 {
@@ -858,14 +834,6 @@ rb_raise_jump(VALUE mesg, VALUE cause)
     rb_longjmp(ec, TAG_RAISE, mesg, cause);
 }
 
-/*!
- * Continues the exception caught by rb_protect() and rb_eval_string_protect().
- *
- * This function never return to the caller.
- * \param[in] the value of \c *state which the protect function has set to the
- *   their last parameter.
- * \ingroup exception
- */
 void
 rb_jump_tag(int tag)
 {
@@ -1060,35 +1028,12 @@ frame_called_id(rb_control_frame_t *cfp)
     }
 }
 
-/*!
- * The original name of the current method.
- *
- * The function returns the original name of the method even if
- * an alias of the method is called.
- * The function can also return 0 if it is not in a method. This
- * case can happen in a toplevel of a source file, for example.
- *
- * \returns the ID of the name or 0
- * \sa rb_frame_callee
- * \ingroup defmethod
- */
 ID
 rb_frame_this_func(void)
 {
     return frame_func_id(GET_EC()->cfp);
 }
 
-/*!
- * The name of the current method.
- *
- * The function returns the alias if an alias of the method is called.
- * The function can also return 0 if it is not in a method. This
- * case can happen in a toplevel of a source file, for example.
- *
- * \returns the ID of the name or 0.
- * \sa rb_frame_this_func
- * \ingroup defmethod
- */
 ID
 rb_frame_callee(void)
 {
@@ -1554,16 +1499,6 @@ rb_mod_s_used_modules(VALUE _)
     return rb_funcall(ary, rb_intern("uniq"), 0);
 }
 
-/*!
- * Calls \c #initialize method of \a obj with the given arguments.
- *
- * It also forwards the given block to \c #initialize if given.
- *
- * \param[in] obj the receiver object
- * \param[in] argc the number of arguments
- * \param[in] argv a pointer to the array of arguments
- * \ingroup object
- */
 void
 rb_obj_call_init(VALUE obj, int argc, const VALUE *argv)
 {

include/ruby/internal/intern/eval.h

@@ -28,31 +28,194 @@ RBIMPL_SYMBOL_EXPORT_BEGIN()
 
 /* eval.c */
 RBIMPL_ATTR_NORETURN()
-void rb_exc_raise(VALUE);
+/**
+ * Identical to rb_raise(), except it  raises the passed exception instance as-
+ * is instead of creating new one.
+ *
+ * @param[in]  exc            An instance of a subclass of ::rb_eException.
+ * @exception  exc            What is passed.
+ * @exception  rb_eTypeError  `exc` is not an exception.
+ * @note       It never returns.
+ *
+ * @internal
+ *
+ * Wellll  actually, it  can  take more  than what  is  described above.   This
+ * function tries  to call `exception`  method of  the passed object.   If that
+ * function returns an exception object that is used instead.
+ */
+void rb_exc_raise(VALUE exc);
 
 RBIMPL_ATTR_NORETURN()
-void rb_exc_fatal(VALUE);
+/**
+ * Identical to rb_fatal(), except it  raises the passed exception instance as-
+ * is instead of creating new one.
+ *
+ * @param[in]  exc  An instance of a subclass of ::rb_eException.
+ * @exception  exc  What is passed.
+ * @note       It never returns.
+ *
+ * @internal
+ *
+ * You know  what...?  Using this API  you can make arbitrary  exceptions, like
+ * `RuntimeError`, that doesn't  interface with `rescue` clause.   This is very
+ * confusing.
+ */
+void rb_exc_fatal(VALUE exc);
+
+/* process.c */
 
 RBIMPL_ATTR_NORETURN()
-VALUE rb_f_exit(int, const VALUE*);
+/**
+ * Identical to rb_exit(), except how arguments are passed.
+ *
+ * @param[in]  argc            Number of objects of `argv`.
+ * @param[in]  argv            Contains at most one of the following:
+ *                               - ::RUBY_Qtrue - means `EXIT_SUCCESS`.
+ *                               - ::RUBY_Qfalse - means `EXIT_FAILURE`.
+ *                               - Numerical value - takes that value.
+ * @exception  rb_eArgError    Wrong `argc`.
+ * @exception  rb_eSystemExit  Exception representing the exit status.
+ * @note       It never returns.
+ */
+VALUE rb_f_exit(int argc, const VALUE *argv);
 
 RBIMPL_ATTR_NORETURN()
-VALUE rb_f_abort(int, const VALUE*);
+/**
+ * This is  similar to rb_f_exit().   In fact  on some situation  it internally
+ * calls rb_exit().  But can be very esoteric on occasions.
+ *
+ * It takes up to one argument.  If  an argument is passed, it tries to display
+ * that.   Otherwise if  there is  `$!`, displays  that exception  instead.  It
+ * finally raise ::rb_eSystemExit in both cases.
+ *
+ * @param[in]  argc            Number of objects of `argv`.
+ * @param[in]  argv            Contains at most one string-ish object.
+ * @exception  rb_eArgError    Wrong `argc`.
+ * @exception  rb_eTypeError   No conversion from `argv[0]` to String.
+ * @exception  rb_eSystemExit  Exception representing `EXIT_FAILURE`.
+ * @note       It never returns.
+ */
+VALUE rb_f_abort(int argc, const VALUE *argv);
+
+/* eval.c*/
 
 RBIMPL_ATTR_NORETURN()
+/**
+ * Raises an instance of ::rb_eInterrupt.
+ *
+ * @exception  rb_eInterrupt  Always raises this exception.
+ * @note       It never returns.
+ */
 void rb_interrupt(void);
+
+/**
+ * Queries the  name of the  Ruby level method  that is calling  this function.
+ * The "name" in this context is the one assigned to the function for the first
+ * time (note that methods can have multiple names via aliases).
+ *
+ * @retval  0          There is no method (e.g. toplevel context).
+ * @retval  otherwise  The name of the current method.
+ */
 ID rb_frame_this_func(void);
 
 RBIMPL_ATTR_NORETURN()
-void rb_jump_tag(int);
+/**
-void rb_obj_call_init(VALUE, int, const VALUE*);
+ * This function  is to re-throw  global escapes.  Such global  escapes include
+ * exceptions, `throw`, `break`, for example.
+ *
+ * It makes  sense only  when used  in conjunction  with "protect"  series APIs
+ * e.g.  rb_protect(),  rb_load_protect(), rb_eval_string_protect(),  etc.   In
+ * case  these functions  experience  global escapes,  they  fill their  opaque
+ * `state` return  buffer.  You  can ignore  such escapes.   But if  you decide
+ * otherwise, you have to somehow escape globally again.  This function is used
+ * for that purpose.
+ *
+ * @param[in]  state  Opaque state of execution.
+ * @note       It never returns.
+ *
+ * @internal
+ *
+ * Though  not  a  part  of  our  public  API,  `state`  is  in  fact  an  enum
+ * ruby_tag_type.  You can see the potential values by looking at vm_core.h.
+ */
+void rb_jump_tag(int state);
+
+/**
+ * Calls `initialize`  method of the  passed object with the  passed arguments.
+ * It also forwards the implicitly passed block to the method.
+ *
+ * @param[in]  obj            Receiver object.
+ * @param[in]  argc           Number of objects of `argv`.
+ * @param[in]  argv           Passed as-is to `obj.initialize`.
+ * @exception  rb_eException  Any exceptions happen inside.
+ */
+void rb_obj_call_init(VALUE obj, int argc, const VALUE *argv);
+
+/**
+ * Identical to  rb_obj_call_init(), except you  can specify how to  handle the
+ * last element of the given array.
+ *
+ * @param[in]  obj                Receiver object.
+ * @param[in]  argc               Number of objects of `argv`.
+ * @param[in]  argv               Passed as-is to `obj.initialize`.
+ * @param[in]  kw_splat           Handling of keyword parameters:
+ *   - RB_NO_KEYWORDS             `argv`'s last is not a keyword argument.
+ *   - RB_PASS_KEYWORDS           `argv`'s last is a keyword argument.
+ *   - RB_PASS_CALLED_KEYWORDS    it depends if there is a passed block.
+ * @exception  rb_eNoMethodError  No such method.
+ * @exception  rb_eException      Any exceptions happen inside.
+ */
 void rb_obj_call_init_kw(VALUE, int, const VALUE*, int);
-VALUE rb_protect(VALUE (*)(VALUE), VALUE, int*);
+
+/**
+ * Identical to rb_frame_this_func(), except it  returns the named used to call
+ * the method.
+ *
+ * @retval  0          There is no method (e.g. toplevel context).
+ * @retval  otherwise  The name of the current method.
+ */
 ID rb_frame_callee(void);
-VALUE rb_make_exception(int, const VALUE*);
+
+/**
+ * Constructs  an exception  object from  the list  of arguments,  in a  manner
+ * similar to Ruby's `raise`.  This function can take:
+ *
+ *   - No arguments  at all,  i.e. `argc  == 0`.   This is  not a  failure.  It
+ *     returns ::RUBY_Qnil then.
+ *
+ *   - An  object, which  is  an instance  of ::rb_cString.   In  this case  an
+ *     instance of  ::rb_eRuntimeError whose  message is  the passed  string is
+ *     created then returned.
+ *
+ *   - An  object, which  responds to  `exception` method,  and optionally  its
+ *     argument,  and  optionally  its  backtrace.  For  example  instances  of
+ *     subclasses of ::rb_eException  have this method.  What  is returned from
+ *     the method is returned.
+ *
+ * @param[in]  argc           Number of objects of `argv`.
+ * @param[in]  argv           0 up to 3 objects.
+ * @exception  rb_eArgError   Wrong `argc`.
+ * @exception  rb_eTypeError  `argv[0].exception` returned non-exception.
+ * @return     An instance of a subclass of ::rb_eException.
+ *
+ * @internal
+ *
+ * Historically  this was  _the_  way  `raise` converted  its  arguments to  an
+ * exception.  However they diverged.
+ */
+VALUE rb_make_exception(int argc, const VALUE *argv);
 
 /* eval_jump.c */
-void rb_set_end_proc(void (*)(VALUE), VALUE);
+
+/**
+ * Registers a function  that shall run on process  exit.  Registered functions
+ * run in  reverse-chronological order,  mixed with  syntactic `END`  block and
+ * `Kernel#at_exit`.
+ *
+ * @param[in]  func  Function to run at process exit.
+ * @param[in]  arg   Passed as-is to `func`.
+ */
+void rb_set_end_proc(void (*func)(VALUE arg), VALUE arg);
 
 RBIMPL_SYMBOL_EXPORT_END()