From f8601bd903d6c9f288fc39cc9f277c1275291ff3 Mon Sep 17 00:00:00 2001 From: yugui Date: Thu, 14 Jun 2012 02:21:51 +0000 Subject: [PATCH] * eval.c: Add doxygen comments. * ruby.c: ditto. * thread_pthread.c: ditto * version.c: ditto. * vm_core.h: ditto. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@36078 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 12 ++++++++++++ eval.c | 45 +++++++++++++++++++++++++++++++++++++++++++++ ruby.c | 12 ++++++++++++ thread_pthread.c | 4 ++++ version.c | 5 +++++ vm_core.h | 11 +++++++++++ 6 files changed, 89 insertions(+) diff --git a/ChangeLog b/ChangeLog index 5fc8702e5b..30c7c4ddd6 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,15 @@ +Thu Jun 14 10:39:48 2012 Yuki Yugui Sonoda + + * eval.c: Add doxygen comments. + + * ruby.c: ditto. + + * thread_pthread.c: ditto + + * version.c: ditto. + + * vm_core.h: ditto. + Thu Jun 14 10:16:07 2012 NARUSE, Yui * configure.in: revert r36071 and add NetBSD to blacklist of -ansi. diff --git a/eval.c b/eval.c index 3ec0e1a282..a706c23dab 100644 --- a/eval.c +++ b/eval.c @@ -61,6 +61,16 @@ ruby_init(void) GET_VM()->running = 1; } +/*! Processes command line arguments and compiles the Ruby source to execute. + * + * This function does: + * \li Processses 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) { @@ -101,6 +111,13 @@ ruby_finalize_1(void) rb_gc_call_finalizer_at_exit(); } +/** Runs the VM finalization processes. + * + * END{} and procs registered by Kernel.#at_ext 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) { @@ -108,6 +125,16 @@ ruby_finalize(void) ruby_finalize_1(); } +/** 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 occured returns a non-zero. If otherwise, reurns the + * given ex. + * @note This function does not raise any exception. + */ int ruby_cleanup(volatile int ex) { @@ -210,12 +237,25 @@ ruby_exec_internal(void *n) 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 + * *status. + * + * @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) { @@ -233,6 +273,10 @@ ruby_executable_node(void *n, int *status) return FALSE; } +/*! Runs the given compiled source and exits this process. + * @retval 0 if successfully run thhe source + * @retval non-zero if an error occurred. +*/ int ruby_run_node(void *n) { @@ -244,6 +288,7 @@ ruby_run_node(void *n) return ruby_cleanup(ruby_exec_node(n)); } +/*! Runs the given compiled source */ int ruby_exec_node(void *n) { diff --git a/ruby.c b/ruby.c index 7db0736f72..beaf198612 100644 --- a/ruby.c +++ b/ruby.c @@ -1706,6 +1706,11 @@ set_arg0(VALUE val, ID id) rb_progname = rb_obj_freeze(rb_external_str_new(s, i)); } +/*! Sets the current script name to this value. + * + * This is similiar to $0 = name in Ruby level but also affects + * Method#location and others. + */ void ruby_script(const char *name) { @@ -1765,6 +1770,7 @@ opt_W_getter(ID id, void *data) } } +/*! Defines built-in variables */ void ruby_prog_init(void) { @@ -1860,6 +1866,12 @@ fill_standard_fds(void) } } +/*! Initializes the process for ruby(1). + * + * This function assumes this process is ruby(1) and it has just started. + * Usually programs that embeds CRuby interpreter should not call this function, + * and should do their own initialization. + */ void ruby_sysinit(int *argc, char ***argv) { diff --git a/thread_pthread.c b/thread_pthread.c index 02ff18517c..06769bd293 100644 --- a/thread_pthread.c +++ b/thread_pthread.c @@ -581,6 +581,10 @@ extern void *STACK_END_ADDRESS; #endif #undef ruby_init_stack +/* Set stack bottom of Ruby implementation. + * + * You must call this function before any heap allocation by Ruby implementation. + * Or GC will break living objects */ void ruby_init_stack(volatile VALUE *addr #ifdef __ia64 diff --git a/version.c b/version.c index 26c3b0d5a4..26e275a2e4 100644 --- a/version.c +++ b/version.c @@ -96,6 +96,7 @@ const char ruby_initial_load_paths[] = #endif ""; +/*! Defines platform-depended Ruby-level constants */ void Init_version(void) { @@ -134,6 +135,7 @@ Init_version(void) rb_define_global_const("RUBY_ENGINE", ruby_engine_name = MKSTR(engine)); } +/*! Prints the version information of the CRuby interpreter to stdout. */ void ruby_show_version(void) { @@ -141,6 +143,9 @@ ruby_show_version(void) fflush(stdout); } +/*! Prints the copyright notice of the CRuby interpreter to stdout and \em exits + * this process successfully. + */ void ruby_show_copyright(void) { diff --git a/vm_core.h b/vm_core.h index e00f32ad09..e77d3b83e5 100644 --- a/vm_core.h +++ b/vm_core.h @@ -458,7 +458,18 @@ typedef struct rb_thread_struct { struct rb_vm_tag *tag; struct rb_vm_protect_tag *protect_tag; + /*! Thread-local state of evaluation context. + * + * If negative, this thread is evaluating the main program. + * If positive, this thread is evaluating a program under Kernel::eval + * family. + */ int parse_in_eval; + + /*! Thread-local state of compiling context. + * + * If non-zero, the parser does not automatically print error messages to + * stderr. */ int mild_compile_error; /* storage */