Document that Kernel#load will load relative to current directory [ci skip]

Update and format the Kernel#load documentation to separate the
three cases (absolute path, explicit relative path, other), and
also document that it raises LoadError on failure.

Fixes [Bug #16988]

1 files changed, 15 insertions, 3 deletions

diff --git a/load.c b/load.c
index 8569287313..b0143b7b82 100644
--- a/load.c
+++ b/load.c
@@ -682,10 +682,22 @@ rb_load_protect(VALUE fname, int wrap, int *pstate)
  *
  *  Loads and executes the Ruby program in the file _filename_.
  *
- *  If the filename neither resolves to an absolute path nor starts with
- *  './' or '../', the file will be searched for in the library
+ *  If the filename is an absolute path (e.g. starts with '/'), the file
+ *  will be loaded directly using the absolute path.
+ *
+ *  If the filename is an explicit relative path (e.g. starts with './' or
+ *  '../'), the file will be loaded using the relative path from the current
+ *  directory.
+ *
+ *  Otherwise, the file will be searched for in the library
  *  directories listed in <code>$LOAD_PATH</code> (<code>$:</code>).
- *  If the filename starts with './' or '../', resolution is based on Dir.pwd.
+ *  If the file is found in a directory, it will attempt to load the file
+ *  relative to that directory.  If the file is not found in any of the
+ *  directories in <code>$LOAD_PATH</code>, the file will be loaded using
+ *  the relative path from the current directory.
+ *
+ *  If the file doesn't exist when there is an attempt to load it, a
+ *  LoadError will be raised.
  *
  *  If the optional _wrap_ parameter is +true+, the loaded script will
  *  be executed under an anonymous module, protecting the calling