Clarify documentation for `InstructionSequence#compile`.

We incorrectly assumed that the `file` argument should be the file name and
caused https://github.com/scoutapp/scout_apm_ruby/issues/307 because
exception backtrace did not contain correct path. This documentation
clarifies the role of the different arguments and provides extra
examples.

1 files changed, 14 insertions, 2 deletions

diff --git a/iseq.c b/iseq.c
index cb179d18b3..b7443a7531 100644
--- a/iseq.c
+++ b/iseq.c
@@ -1156,10 +1156,14 @@ rb_iseqw_new(const rb_iseq_t *iseq)
  *  Takes +source+, a String of Ruby code and compiles it to an
  *  InstructionSequence.
  *
- *  Optionally takes +file+, +path+, and +line+ which describe the filename,
- *  absolute path and first line number of the ruby code in +source+ which are
+ *  Optionally takes +file+, +path+, and +line+ which describe the file path,
+ *  real path and first line number of the ruby code in +source+ which are
  *  metadata attached to the returned +iseq+.
  *
+ *  +file+ is used for `__FILE__` and exception backtrace. +path+ is used for
+ *  +require_relative+ base. It is recommended these should be the same full
+ *  path.
+ *
  *  +options+, which can be +true+, +false+ or a +Hash+, is used to
  *  modify the default behavior of the Ruby iseq compiler.
  *
@@ -1168,6 +1172,14 @@ rb_iseqw_new(const rb_iseq_t *iseq)
  *     RubyVM::InstructionSequence.compile("a = 1 + 2")
  *     #=> <RubyVM::InstructionSequence:<compiled>@<compiled>>
  *
+ *     path = "test.rb"
+ *     RubyVM::InstructionSequence.compile(File.read(path), path, File.expand_path(path))
+ *     #=> <RubyVM::InstructionSequence:<compiled>@test.rb:1>
+ *
+ *     path = File.expand_path("test.rb")
+ *     RubyVM::InstructionSequence.compile(File.read(path), path, path)
+ *     #=> <RubyVM::InstructionSequence:<compiled>@/absolute/path/to/test.rb:1>
+ *
  */
 static VALUE
 iseqw_s_compile(int argc, VALUE *argv, VALUE self)