From 39a43d9cd09f8c880d0a70d9cb8ede6d7e6ef583 Mon Sep 17 00:00:00 2001 From: Benoit Daloze Date: Mon, 19 Aug 2019 13:51:00 +0800 Subject: Make it as clear as possible that RubyVM is MRI-specific and only exists on MRI (#2113) [ci skip] * Make it clear as possible that RubyVM is MRI-specific and only exists on MRI * See [Bug #15743]. * Use "CRuby VM" instead of "Ruby VM" for clarity. * Use YARV rather than "CRuby VM" for documenting RubyVM::InstructionSequence * Avoid introducing a new "CRuby VM" term in documentation --- ast.c | 5 +++++ eval.c | 2 +- iseq.c | 6 ++++-- vm.c | 23 ++++++++++++++++++----- 4 files changed, 28 insertions(+), 8 deletions(-) diff --git a/ast.c b/ast.c index 4c6477d3c9..91659a9110 100644 --- a/ast.c +++ b/ast.c @@ -776,11 +776,16 @@ Init_ast(void) * AbstractSyntaxTree provides methods to parse Ruby code into * abstract syntax trees. The nodes in the tree * are instances of RubyVM::AbstractSyntaxTree::Node. + * + * This class is MRI specific as it exposes implementation details + * of the MRI abstract syntax tree. */ rb_mAST = rb_define_module_under(rb_cRubyVM, "AbstractSyntaxTree"); /* * RubyVM::AbstractSyntaxTree::Node instances are created by parse methods in * RubyVM::AbstractSyntaxTree. + * + * This class is MRI specific. */ rb_cNode = rb_define_class_under(rb_mAST, "Node", rb_cObject); diff --git a/eval.c b/eval.c index 3bd70f66c3..01e4fa6e42 100644 --- a/eval.c +++ b/eval.c @@ -47,7 +47,7 @@ extern ID ruby_static_id_cause; (BUILTIN_TYPE(obj) == T_CLASS || BUILTIN_TYPE(obj) == T_MODULE)) /*! - * Initializes the Ruby VM and builtin libraries. + * Initializes the VM and builtin libraries. * @retval 0 if succeeded. * @retval non-zero an error occurred. */ diff --git a/iseq.c b/iseq.c index 7f1e2203cb..5c63922b0d 100644 --- a/iseq.c +++ b/iseq.c @@ -3456,14 +3456,14 @@ succ_index_lookup(const struct succ_index_table *sd, int x) * Document-class: RubyVM::InstructionSequence * * The InstructionSequence class represents a compiled sequence of - * instructions for the Ruby Virtual Machine. Not all implementations of Ruby + * instructions for the Virtual Machine used in MRI. Not all implementations of Ruby * may implement this class, and for the implementations that implement it, * the methods defined and behavior of the methods can change in any version. * * With it, you can get a handle to the instructions that make up a method or * a proc, compile strings of Ruby code down to VM instructions, and * disassemble instruction sequences to strings for easy inspection. It is - * mostly useful if you want to learn how the Ruby VM works, but it also lets + * mostly useful if you want to learn how YARV works, but it also lets * you control various settings for the Ruby iseq compiler. * * You can find the source for the VM instructions in +insns.def+ in the Ruby @@ -3472,6 +3472,8 @@ succ_index_lookup(const struct succ_index_table *sd, int x) * The instruction sequence results will almost certainly change as Ruby * changes, so example output in this documentation may be different from what * you see. + * + * Of course, this class is MRI specific. */ void diff --git a/vm.c b/vm.c index e8e436bd80..2ee9d84ae2 100644 --- a/vm.c +++ b/vm.c @@ -2913,9 +2913,13 @@ Init_VM(void) /* * Document-class: RubyVM * - * The RubyVM module provides some access to Ruby internals. + * The RubyVM module only exists on MRI. +RubyVM+ is not defined in + * other Ruby implementations such as JRuby and TruffleRuby. + * + * The RubyVM module provides some access to MRI internals. * This module is for very limited purposes, such as debugging, * prototyping, and research. Normal users must not use it. + * This module is not portable between Ruby implementations. */ rb_cRubyVM = rb_define_class("RubyVM", rb_cObject); rb_undef_alloc_func(rb_cRubyVM); @@ -2945,7 +2949,10 @@ Init_VM(void) rb_gc_register_mark_object(fcore); rb_mRubyVMFrozenCore = fcore; - /* RubyVM::MJIT */ + /* ::RubyVM::MJIT + * Provides access to the Method JIT compiler of MRI. + * Of course, this module is MRI specific. + */ mjit = rb_define_module_under(rb_cRubyVM, "MJIT"); rb_define_singleton_method(mjit, "enabled?", mjit_enabled_p, 0); rb_define_singleton_method(mjit, "pause", mjit_pause_m, -1); @@ -3134,7 +3141,10 @@ Init_VM(void) rb_define_singleton_method(rb_cRubyVM, "USAGE_ANALYSIS_REGISTER_CLEAR", usage_analysis_register_clear, 0); #endif - /* ::RubyVM::OPTS, which shows vm build options */ + /* ::RubyVM::OPTS + * An Array of VM build options. + * This constant is MRI specific. + */ rb_define_const(rb_cRubyVM, "OPTS", opts = rb_ary_new()); #if OPT_DIRECT_THREADED_CODE @@ -3161,11 +3171,14 @@ Init_VM(void) rb_ary_push(opts, rb_str_new2("block inlining")); #endif - /* ::RubyVM::INSTRUCTION_NAMES */ + /* ::RubyVM::INSTRUCTION_NAMES + * A list of bytecode instruction names in MRI. + * This constant is MRI specific. + */ rb_define_const(rb_cRubyVM, "INSTRUCTION_NAMES", rb_insns_name_array()); /* ::RubyVM::DEFAULT_PARAMS - * This constant variable shows VM's default parameters. + * This constant exposes the VM's default parameters. * Note that changing these values does not affect VM execution. * Specification is not stable and you should not depend on this value. * Of course, this constant is MRI specific. -- cgit v1.2.3