ruby-changes:67740
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:01:19 +0900 (JST)
Subject: [ruby-changes:67740] f83b14af24 (master): include/ruby/internal/interpreter.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=f83b14af24 From f83b14af247c56083fa19f2f0ca47ba4088b324f 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: Fri, 18 Dec 2020 14:24:07 +0900 Subject: include/ruby/internal/interpreter.h: add doxygen Must not be a bad idea to improve documents. [ci skip] In fact many functions declared in the header file are already documented more or less. They were just copy & pasted, with applying some style updates. --- eval.c | 55 --------- include/ruby/internal/interpreter.h | 237 ++++++++++++++++++++++++++++++++++-- ruby.c | 13 -- thread_pthread.c | 4 - version.c | 2 - 5 files changed, 226 insertions(+), 85 deletions(-) diff --git a/eval.c b/eval.c index a2cd523..ff05984 100644 --- a/eval.c +++ b/eval.c @@ -61,11 +61,6 @@ extern ID ruby_static_id_cause; https://github.com/ruby/ruby/blob/trunk/eval.c#L61 (!SPECIAL_CONST_P(obj) && \ (BUILTIN_TYPE(obj) == T_CLASS || BUILTIN_TYPE(obj) == T_MODULE)) -/*! - * Initializes the VM and builtin libraries. - * @retval 0 if succeeded. - * @retval non-zero an error occurred. - */ int ruby_setup(void) { @@ -99,11 +94,6 @@ ruby_setup(void) https://github.com/ruby/ruby/blob/trunk/eval.c#L94 return state; } -/*! - * Calls ruby_setup() and check error. - * - * Prints errors and calls exit(3) if an error occurred. - */ void ruby_init(void) { @@ -115,16 +105,6 @@ ruby_init(void) https://github.com/ruby/ruby/blob/trunk/eval.c#L105 } } -/*! Processes command line arguments and compiles the Ruby source to execute. - * - * This function does: - * \li Processes the given command line flags and arguments for ruby(1) - * \li compiles the source code from the given argument, -e or stdin, and - * \li returns the compiled source as an opaque pointer to an internal data structure - * - * @return an opaque pointer to the compiled source or an internal special value. - * @sa ruby_executable_node(). - */ void * ruby_options(int argc, char **argv) { @@ -184,13 +164,6 @@ rb_ec_finalize(rb_execution_context_t *ec) https://github.com/ruby/ruby/blob/trunk/eval.c#L164 rb_objspace_call_finalizer(rb_ec_vm_ptr(ec)->objspace); } -/** Runs the VM finalization processes. - * - * <code>END{}</code> and procs registered by <code>Kernel.#at_exit</code> are - * executed here. See the Ruby language spec for more details. - * - * @note This function is allowed to raise an exception if an error occurred. - */ void ruby_finalize(void) { @@ -199,16 +172,6 @@ ruby_finalize(void) https://github.com/ruby/ruby/blob/trunk/eval.c#L172 rb_ec_finalize(ec); } -/** Destructs the VM. - * - * Runs the VM finalization processes as well as ruby_finalize(), and frees - * resources used by the VM. - * - * @param ex Default value to the return value. - * @return If an error occurred returns a non-zero. If otherwise, returns the - * given ex. - * @note This function does not raise any exception. - */ int ruby_cleanup(int ex) { @@ -322,25 +285,12 @@ rb_ec_exec_node(rb_execution_context_t *ec, void *n) https://github.com/ruby/ruby/blob/trunk/eval.c#L285 return state; } -/*! Calls ruby_cleanup() and exits the process */ void ruby_stop(int ex) { exit(ruby_cleanup(ex)); } -/*! Checks the return value of ruby_options(). - * @param n return value of ruby_options(). - * @param status pointer to the exit status of this process. - * - * ruby_options() sometimes returns a special value to indicate this process - * should immediately exit. This function checks if the case. Also stores the - * exit status that the caller have to pass to exit(3) into - * <code>*status</code>. - * - * @retval non-zero if the given opaque pointer is actually a compiled source. - * @retval 0 if the given value is such a special value. - */ int ruby_executable_node(void *n, int *status) { @@ -358,10 +308,6 @@ ruby_executable_node(void *n, int *status) https://github.com/ruby/ruby/blob/trunk/eval.c#L308 return FALSE; } -/*! Runs the given compiled source and exits this process. - * @retval 0 if successfully run the source - * @retval non-zero if an error occurred. -*/ int ruby_run_node(void *n) { @@ -375,7 +321,6 @@ ruby_run_node(void *n) https://github.com/ruby/ruby/blob/trunk/eval.c#L321 return rb_ec_cleanup(ec, rb_ec_exec_node(ec, n)); } -/*! Runs the given compiled source */ int ruby_exec_node(void *n) { diff --git a/include/ruby/internal/interpreter.h b/include/ruby/internal/interpreter.h index d66fcef..f8dd9bf 100644 --- a/include/ruby/internal/interpreter.h +++ b/include/ruby/internal/interpreter.h @@ -21,6 +21,7 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/interpreter.h#L21 * @brief Interpreter embedding APIs. */ #include "ruby/internal/attr/noreturn.h" +#include "ruby/internal/attr/nonnull.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" @@ -28,65 +29,279 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/interpreter.h#L29 /** * @defgroup embed CRuby Embedding APIs + * * CRuby interpreter APIs. These are APIs to embed MRI interpreter into your * program. * These functions are not a part of Ruby extension library API. * Extension libraries of Ruby should not depend on these functions. + * * @{ */ -/** @defgroup ruby1 ruby(1) implementation +/** + * @defgroup ruby1 ruby(1) implementation + * * A part of the implementation of ruby(1) command. * Other programs that embed Ruby interpreter do not always need to use these * functions. + * * @{ */ +RBIMPL_ATTR_NONNULL(()) +/** + * Initializes the process for libruby. + * + * This function assumes this process is `ruby(1)` and it has just started. + * Usually programs that embed CRuby interpreter may not call this function, + * and may do their own initialization. + * + * @param[in] argc Pointer to process main's `argc`. + * @param[in] argv Pointer to process main's `argv`. + * @warning `argc` and `argv` cannot be `NULL`. + * + * @internal + * + * AFAIK Ruby does write to argv, especially `argv[0][0]`, via setproctitle(3). + * It is intentional that the argument is not const-qualified. + */ void ruby_sysinit(int *argc, char ***argv); + +/** + * Calls ruby_setup() and check error. + * + * Prints errors and calls exit(3) if an error occurred. + */ void ruby_init(void); + +/** + * Processes command line arguments and compiles the Ruby source to execute. + * + * This function does: + * - Processes the given command line flags and arguments for `ruby(1)` + * - Compiles the source code from the given argument, `-e` or `stdin`, and + * - Returns the compiled source as an opaque pointer to an internal data + * structure + * + * @param[in] argc Process main's `argc`. + * @param[in] argv Process main's `argv`. + * @return An opaque pointer to the compiled source or an internal special + * value. Pass it to ruby_executable_node() to detect which. + * @see ruby_executable_node + */ void* ruby_options(int argc, char** argv); + +/** + * Checks the return value of ruby_options(). + * + * ruby_options() sometimes returns a special value to indicate this process + * should immediately exit. This function checks if the case. Also stores the + * exit status that the caller have to pass to exit(3) into `*status`. + * + * @param[in] n A return value of ruby_options(). + * @param[out] status Pointer to the exit status of this process. + * @retval 0 The given value is such a special value. + * @retval otherwise The given opaque pointer is actually a compiled + * source. + */ int ruby_executable_node(void *n, int *status); + +/** + * Runs the given compiled source and exits this process. + * + * @param[in] n Opaque "node" pointer. + * @retval EXIT_SUCCESS Successfully run the source. + * @retval EXIT_FAILURE An error occurred. + */ int ruby_run_node(void *n); /* version.c */ +/** Prints the version information of the CRuby interpreter to stdout. */ void ruby_show_version(void); + #ifndef ruby_show_copyright +/** Prints the copyright notice of the CRuby interpreter to stdout. */ void ruby_show_copyright(void); #endif -/*! A convenience macro to call ruby_init_stack(). Must be placed just after - * variable declarations */ +/** + * A convenience macro to call ruby_init_stack(). + * Must be placed just after variable declarations. + */ #define RUBY_INIT_STACK \ VALUE variable_in_this_stack_frame; \ ruby_init_stack(&variable_in_this_stack_frame); -/*! @} */ +/** @} */ -void ruby_init_stack(volatile VALUE*); +/** + * Set stack bottom of Ruby implementation. + * + * You must call this function before any heap allocation by Ruby + * implementation. Or GC will break living objects. + * + * @param[in] addr A pointer somewhere on the stack, near its bottom. + */ +void ruby_init_stack(volatile VALUE *addr); +/** + * Initializes the VM and builtin libraries. + * + * @retval 0 Initialization succeeded. + * @retval otherwise An error occurred. + * + * @internal + * + * Though not a part of our public API, the return value is in fact an enum + * ruby_tag_type. You can see the potential "otherwise" values by looking at + * vm_core.h. + */ int ruby_setup(void); -int ruby_cleanup(int); +/** + * Destructs the VM. + * + * Runs the VM finalization processes as well as ruby_finalize(), and frees + * resources used by the VM. + * + * @param[in] ex Default value to the return value. + * @retval EXIT_FAILURE An error occurred. + * @retval ex Successful cleanup. + * @note This function does not raise any exception. + */ +int ruby_cleanup( +#if !defined(__cplusplus) || __cplusplus <= 201704L + volatile /* C++20 killed volatile. cf: http://wg21.link/P (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/