[前][次][番号順一覧][スレッド一覧]

ruby-changes:67722

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:67722] 30f3319871 (master): include/ruby/internal/eval.h: add doxygen

https://git.ruby-lang.org/ruby.git/commit/?id=30f3319871

From 30f33198714555abc9ed004b75b4508a39922335 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, 1 Feb 2021 14:10:07 +0900
Subject: include/ruby/internal/eval.h: add doxygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/eval.h | 353 +++++++++++++++++++++++++++++++++++++++++--
 vm_eval.c                    |  59 +-------
 2 files changed, 339 insertions(+), 73 deletions(-)

diff --git a/include/ruby/internal/eval.h b/include/ruby/internal/eval.h
index 5dda3c7..34a5384 100644
--- a/include/ruby/internal/eval.h
+++ b/include/ruby/internal/eval.h
@@ -21,28 +21,351 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/eval.h#L21
  * @brief      Declares ::rb_eval_string().
  */
 #include "ruby/internal/dllexport.h"
+#include "ruby/internal/attr/nonnull.h"
 #include "ruby/internal/value.h"
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
 
-VALUE rb_eval_string(const char*);
-VALUE rb_eval_string_protect(const char*, int*);
-VALUE rb_eval_string_wrap(const char*, int*);
-VALUE rb_funcall(VALUE, ID, int, ...);
-VALUE rb_funcallv(VALUE, ID, int, const VALUE*);
-VALUE rb_funcallv_kw(VALUE, ID, int, const VALUE*, int);
-VALUE rb_funcallv_public(VALUE, ID, int, const VALUE*);
-VALUE rb_funcallv_public_kw(VALUE, ID, int, const VALUE*, int);
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Evaluates the given string in an isolated binding.
+ *
+ * Here  "isolated"  means  that  the   binding  does  not  inherit  any  other
+ * bindings.  This behaves same as the binding for required libraries.
+ *
+ * `__FILE__`  will  be  `"(eval)"`,  and  `__LINE__`  starts  from  1  in  the
+ * evaluation.
+ *
+ * @param[in]  str            Ruby code to evaluate.
+ * @exception  rb_eException  Raises an exception on error.
+ * @return     The evaluated result.
+ */
+VALUE rb_eval_string(const char *str);
+
+RBIMPL_ATTR_NONNULL((1))
+/**
+ * Identical to  rb_eval_string(), except  it avoids potential  global escapes.
+ * Such global escapes include exceptions, `throw`, `break`, for example.
+ *
+ * It first evaluates the given string  as rb_eval_string() does.  If no global
+ * escape occurred during the evaluation, it returns the result and `*state` is
+ * zero.   Otherwise, it  returns some  undefined  value and  sets `*state`  to
+ * nonzero.  If state is `NULL`, it is not set in both cases.
+ *
+ * @param[in]   str    Ruby code to evaluate.
+ * @param[out]  state  State of execution.
+ * @return      The  evaluated  result  if  succeeded, an  undefined  value  if
+ *              otherwise.
+ * @post        `*state` is set to zero if succeeded.  Nonzero otherwise.
+ * @warning     You have to clear the error info with `rb_set_errinfo(Qnil)` if
+ *              you decide to ignore the caught exception.
+ * @see         rb_eval_string
+ * @see         rb_protect
+ *
+ * @internal
+ *
+ * The "undefined value"  described above is in fact ::RUBY_Qnil  for now.  But
+ * @shyouhei doesn't think that we would never change that.
+ *
+ * Though   not  a   part  of   our  public   API,  `state`   is  in   fact  an
+ * enum ruby_tag_type.  You can  see the potential "nonzero"  values by looking
+ * at vm_core.h.
+ */
+VALUE rb_eval_string_protect(const char *str, int *state);
+
+RBIMPL_ATTR_NONNULL((1))
+/**
+ * Identical to rb_eval_string_protect(), except  it evaluates the given string
+ * under  a module  binding in  an isolated  binding.  This  is the  same as  a
+ * binding for loaded libraries on `rb_load(something, true)`.
+ *
+ * @param[in]   str    Ruby code to evaluate.
+ * @param[out]  state  State of execution.
+ * @return      The  evaluated  result  if  succeeded, an  undefined  value  if
+ *              otherwise.
+ * @post        `*state` is set to zero if succeeded.  Nonzero otherwise.
+ * @warning     You have to clear the error info with `rb_set_errinfo(Qnil)` if
+ *              you decide to ignore the caught exception.
+ * @see         rb_eval_string
+ */
+VALUE rb_eval_string_wrap(const char *str, int *state);
+
+/**
+ * Calls a method.  Can call both public and private methods.
+ *
+ * @param[in,out]  recv               Receiver of the method.
+ * @param[in]      mid                Name of the method to call.
+ * @param[in]      n                  Number of arguments that follow.
+ * @param[in]      ...                Arbitrary number of method arguments.
+ * @exception      rb_eNoMethodError  No such method.
+ * @exception      rb_eException      Any exceptions happen inside.
+ * @return         What the method evaluates to.
+ */
+VALUE rb_funcall(VALUE recv, ID mid, int n, ...);
+
+/**
+ * Identical  to rb_funcall(),  except it  takes the  method arguments  as a  C
+ * array.
+ *
+ * @param[in,out]  recv               Receiver of the method.
+ * @param[in]      mid                Name of the method to call.
+ * @param[in]      argc               Number of arguments.
+ * @param[in]      argv               Arbitrary number of method arguments.
+ * @exception      rb_eNoMethodError  No such method.
+ * @exception      rb_eException      Any exceptions happen inside.
+ * @return         What the method evaluates to.
+ */
+VALUE rb_funcallv(VALUE recv, ID mid, int argc, const VALUE *argv);
+
+/**
+ * Identical to  rb_funcallv(), except you can  specify how to handle  the last
+ * element of the given array.
+ *
+ * @param[in,out]  recv               Receiver of the method.
+ * @param[in]      mid                Name of the method to call.
+ * @param[in]      argc               Number of arguments.
+ * @param[in]      argv               Arbitrary number of method arguments.
+ * @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.
+ * @return         What the method evaluates to.
+ */
+VALUE rb_funcallv_kw(VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat);
+
+/**
+ * Identical  to  rb_funcallv(),  except  it only  takes  public  methods  into
+ * account.  This is roughly Ruby's `Object#public_send`.
+ *
+ * @param[in,out]  recv               Receiver of the method.
+ * @param[in]      mid                Name of the method to call.
+ * @param[in]      argc               Number of arguments.
+ * @param[in]      argv               Arbitrary number of method arguments.
+ * @exception      rb_eNoMethodError  No such method.
+ * @exception      rb_eNoMethodError  The method is private or protected.
+ * @exception      rb_eException      Any exceptions happen inside.
+ * @return         What the method evaluates to.
+ */
+VALUE rb_funcallv_public(VALUE recv, ID mid, int argc, const VALUE *argv);
+
+/**
+ * Identical to rb_funcallv_public(), except you  can specify how to handle the
+ * last element of the given array.  It can also be seen as a routine identical
+ * to rb_funcallv_kw(), except it only takes public methods into account.
+ *
+ * @param[in,out]  recv               Receiver of the method.
+ * @param[in]      mid                Name of the method to call.
+ * @param[in]      argc               Number of arguments.
+ * @param[in]      argv               Arbitrary number of method arguments.
+ * @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_eNoMethodError  The method is private or protected.
+ * @exception      rb_eException      Any exceptions happen inside.
+ * @return         What the method evaluates to.
+ */
+VALUE rb_funcallv_public_kw(VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat);
+
+/**
+ * @deprecated   This  is an  old  name of  rb_funcallv().   Provided here  for
+ *               backwards compatibility  to 2.x programs (introduced  in 2.1).
+ *               It is not a good name.  Please don't use it any longer.
+ */
 #define rb_funcall2 rb_funcallv
+
+/**
+ * @deprecated   This is  an old  name of rb_funcallv_public().   Provided here
+ *               for  backwards compatibility  to 2.x  programs (introduced  in
+ *               2.1).  It is not a good name.  Please don't use it any longer.
+ */
 #define rb_funcall3 rb_funcallv_public
-VALUE rb_funcall_passing_block(VALUE, ID, int, const VALUE*);
-VALUE rb_funcall_passing_block_kw(VALUE, ID, int, const VALUE*, int);
-VALUE rb_funcall_with_block(VALUE, ID, int, const VALUE*, VALUE);
-VALUE rb_funcall_with_block_kw(VALUE, ID, int, const VALUE*, VALUE, int);
-VALUE rb_call_super(int, const VALUE*);
-VALUE rb_call_super_kw(int, const VALUE*, int);
+
+/**
+ * Identical to rb_funcallv_public(), except you can pass the passed block.
+ *
+ * Sometimes you want  to "pass" a block parameter form  one method to another.
+ * Suppose you have this Ruby method `foo`:
+ *
+ * ```ruby
+ * def foo(x, y, &z)
+ *   x.open(y, &z)
+ * end
+ * ```
+ *
+ * And    suppose   you    want    to   translate    this    into   C.     Then
+ * rb_funcall_passing_block() function is usable in this situation.
+ *
+ * ```CXX
+ * VALUE
+ * foo_translated_into_C(VALUE self, VALUE x, VALUE y)
+ * {
+ *     const auto open = rb_intern("open");
+ *
+ *     return rb_funcall_passing_block(x, open, 1, &y);
+ * }
+ * ```
+ *
+ * @see            rb_yield_block
+ * @param[in,out]  recv               Receiver of the method.
+ * @param[in]      mid                Name of the method to call.
+ * @param[in]      argc               Number of arguments.
+ * @param[in]      argv               Arbitrary number of method arguments.
+ * @e (... truncated)

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

[前][次][番号順一覧][スレッド一覧]