ruby-changes:67768
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:01:47 +0900 (JST)
Subject: [ruby-changes:67768] 43cac51277 (master): include/ruby/internal/intern/vm.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=43cac51277 From 43cac51277ab2c0e713b549a5a64c05aedc8bcfc 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, 4 Feb 2021 17:35:39 +0900 Subject: include/ruby/internal/intern/vm.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/internal/intern/vm.h | 401 ++++++++++++++++++++++++++++++++++++-- include/ruby/internal/method.h | 1 + vm.c | 2 - vm_eval.c | 8 - 4 files changed, 381 insertions(+), 31 deletions(-) diff --git a/include/ruby/internal/intern/vm.h b/include/ruby/internal/intern/vm.h index bfb32a2..562d30a 100644 --- a/include/ruby/internal/intern/vm.h +++ b/include/ruby/internal/intern/vm.h @@ -18,8 +18,9 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/vm.h#L18 * Do not expect for instance `__VA_ARGS__` is always available. * We assume C99 for ruby itself but we don't assume languages of * extension libraries. They could be written in C++98. - * @brief Public APIs related to ::rb_cRubyVM. + * @brief Public APIs related to rb_cRubyVM. */ +#include "ruby/internal/attr/nonnull.h" #include "ruby/internal/attr/noreturn.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" @@ -27,40 +28,378 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/intern/vm.h#L28 RBIMPL_SYMBOL_EXPORT_BEGIN() /* vm.c */ + +/** + * Resembles `__LINE__`. + * + * @retval 0 Current execution context not in a ruby method. + * @retval otherwise The current line number of the current thread of the + * current ractor of the current execution context. + */ int rb_sourceline(void); + +/** + * Resembles `__FILE__`. + * + * @retval 0 Current execution context not in a ruby method. + * @retval otherwise The current source path of the current thread of the + * current ractor of the current execution context. + * @note This may or may not be an absolute path. + */ const char *rb_sourcefile(void); + +/** + * Resembles `__method__`. + * + * @param[out] idp Return buffer for method id. + * @param[out] klassp Return buffer for class. + * @retval 0 Current execution context not in a method. + * @retval 1 Successful return. + * @post Upon successful return `*idp` and `*klassp` are updated to have + * the current method name and its defined class respectively. + * @note Both parameters can be `NULL`. + */ int rb_frame_method_id_and_class(ID *idp, VALUE *klassp); /* vm_eval.c */ -VALUE rb_check_funcall(VALUE, ID, int, const VALUE*); -VALUE rb_check_funcall_kw(VALUE, ID, int, const VALUE*, int); -void rb_remove_method(VALUE, const char*); -void rb_remove_method_id(VALUE, ID); -VALUE rb_eval_cmd_kw(VALUE, VALUE, int); -VALUE rb_apply(VALUE, ID, VALUE); +/** + * Identical to rb_funcallv(), except it returns ::RUBY_Qundef instead of + * raising ::rb_eNoMethodError. + * + * @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. + * @retval RUBY_Qundef `recv` doesn't respond to `mid`. + * @retval otherwise What the method evaluates to. + */ +VALUE rb_check_funcall(VALUE recv, ID mid, int argc, const VALUE *argv); + +/** + * Identical to rb_check_funcall(), 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 returns ::RUBY_Qundef instead of raising + * ::rb_eNoMethodError. + * + * @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. + * @retval RUBY_Qundef `recv` doesn't respond to `mid`. + * @retval otherwise What the method evaluates to. + */ +VALUE rb_check_funcall_kw(VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat); + +/** + * This API is practically a variant of rb_proc_call_kw() now. Historically + * when there still was a concept called `$SAFE`, this was an API for that. + * But we no longer have that. This function basically ended its role. It + * just remains here because of no harm. + * + * @param[in] cmd A string, or something callable. + * @param[in] arg Argument passed to the call. + * @param[in] kw_splat Handling of keyword parameters: + * - RB_NO_KEYWORDS `arg`'s last is not a keyword argument. + * - RB_PASS_KEYWORDS `arg`'s last is a keyword argument. + * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * @return What the command evaluates to. + */ +VALUE rb_eval_cmd_kw(VALUE cmd, VALUE arg, int kw_splat); + +/** + * Identical to rb_funcallv(), except it takes Ruby's array instead of C's. + * @param[in,out] recv Receiver of the method. + * @param[in] mid Name of the method to call. + * @param[in] args An instance of ::RArray. + * @exception rb_eNoMethodError No such method. + * @exception rb_eException Any exceptions happen inside. + * @return What the method evaluates to. + * @pre `args` must be an ::RArray. Call `to_ary` beforehand when + * necessary. + */ +VALUE rb_apply(VALUE recv, ID mid, VALUE args); + +/** + * Evaluates a string containing Ruby source code, or the given block, within + * the context of the receiver. In order to set the context, the variable + * `self` is set to `recv` while the code is executing, giving the code access + * to `recv`'s instance variables and private methods. + * + * When given a block, `recv` is also passed in as the block's only argument. + * + * When given a string, the optional second and third parameters supply a + * filename and starting line number that are used when reporting compilation + * errors. + * + * @param[in] argc Number of objects in `argv` + * @param[in] argv C array of 0 up to 3 elements. + * @param[in] recv The object in question. + * @return What was evaluated. + */ +VALUE rb_obj_instance_eval(int argc, const VALUE *argv, VALUE recv); + +/** + * Executes the given block within the context of the receiver. In order to + * set the context, the variable `self` is set to `recv` while the code is + * executing, giving the code access to `recv`'s instance variables. Arguments + * are passed as block parameters. + * + * @param[in] argc Number of objects in `argv` + * @param[in] argv Arbitrary parameters to be passed to the block. + * @param[in] recv The object in question. + * @return What was evaluated. + * @note Don't confuse this with rb_obj_instance_eval(). The key + * difference is whether you can pass arbitrary parameters to the + * block, like this: + * + * ```ruby + * class Foo + * def initialize + * @foo = 5 + * end + * end + * Foo.new.instance_exec(7) {|i| @foo + i } # => 12 + * ``` + */ +VALUE rb_obj_instance_exec(int argc, const VALUE *argv, VALUE recv); + +/** + * Identical to rb_obj_instance_eval(), except it evaluates within the context + * of module. + * + * @param[in] argc Number of objects in `argv` + * @param[in] argv C array of 0 up to 3 elements. + * @param[in] mod The module in question. + * @pre `mod` must be a Module. + * @return What was evaluated. + */ +VALUE rb_mod_module_eval(int argc, const VALUE *argv, VALUE mod); -VALUE rb_obj_instance_eval(int, const VALUE*, VALUE); -VALUE rb_obj_instance_exec(int, const VALUE*, VALUE); -VALUE rb_mod_module_eval(int, const VALUE*, VALUE); -VALUE rb_mod_module_exec(int, const VALUE*, VALUE); +/** + * Identical to rb_obj_instance_exec(), except it evaluates within the context + * of module. + * + * @param[in] argc Number of objects in `argv` + * @param[in] argv Arbitrary parameters to be passed to the block. + * @param[in] mod The module in question. + * @pre `mod` must be a Module. + * @return What was evaluated. + */ +VALUE rb_mod_module_exec(int argc, const VALUE *argv, VALUE mod); /* vm_method.c */ + +/** + * @private + * + * @deprecated This macro once was a thing in the old days, but makes no sense + * any longer today. Exists here for backwards compatibility + * only. You can safely forget about it. + */ #define HAVE_RB_DEFINE_ALLOC_FUNC 1 -typedef VALUE (*rb_alloc_func_t)(VALUE); -void rb_define_alloc_func(VALUE, rb_alloc_func_t); -void rb_undef_alloc_func(VALUE); -rb_alloc_func_t rb_get_alloc_func(VALUE); + +/** + * This is the type of functions that ruby calls when trying to allocate an + * object. It is sometimes necessary to allocate extra memory regions for an + * object. When you define a class that uses ::RTypedData, it is typically the + * case. On such situations define a function of this type and pass it to + * rb_define_alloc_func(). + * + * @param[in] klass The class that this function is registered. + * @return A newly allocated instance of `klass`. + */ +typedef VALUE (*rb_alloc_func_t)(VALUE klass); + +/** + * Sets the allocator function of a class. + * + * @param[out] klass The class to modify. + * @param[in] func An allocator function for the class. + * @pre `klass` must be an instance of Class. + */ + (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/