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

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.