* load.c (rb_f_require): Improve documentation of Kernel#require.

[Ruby 1.9 - Bug #5210]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@33027 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,8 @@
+Tue Aug 23 15:23:56 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* load.c (rb_f_require):  Improve documentation of Kernel#require.
+	  [Ruby 1.9 - Bug #5210]
+
 Tue Aug 23 11:27:26 2011  Hiroshi Nakamura  <nahi@ruby-lang.org>
 
 	* ext/zlib/zlib.c (gzfile_read_header): Ensure that each section of

load.c

@@ -430,24 +430,33 @@ load_unlock(const char *ftptr, int done)
 
 /*
  *  call-seq:
- *     require(string)    -> true or false
+ *     require(name)    -> true or false
  *
- *  Ruby tries to load the library named _string_, returning
+ *  Loads the given +name+, returning +true+ if successful and +false+ if the
- *  +true+ if successful. If the filename does not resolve to
+ *  feature is already loaded.
- *  an absolute path, it will be searched for in the directories listed
- *  in <code>$:</code>. If the file has the extension ``.rb'', it is
- *  loaded as a source file; if the extension is ``.so'', ``.o'', or
- *  ``.dll'', or whatever the default shared library extension is on
- *  the current platform, Ruby loads the shared library as a Ruby
- *  extension. Otherwise, Ruby tries adding ``.rb'', ``.so'', and so on
- *  to the name. The name of the loaded feature is added to the array in
- *  <code>$"</code>. A feature will not be loaded if its name already
- *  appears in <code>$"</code>. The file name is converted to an absolute
- *  path, so ``<code>require 'a'; require './a'</code>'' will not load
- *  <code>a.rb</code> twice.
  *
- *     require "my-library.rb"
+ *  If the filename does not resolve to an absolute path, it will be searched
- *     require "db-driver"
+ *  for in the directories listed in <code>$LOAD_PATH</code> (<code>$:</code>).
+ *
+ *  If the filename has the extension ".rb", it is loaded as a source file; if
+ *  the extension is ".so", ".o", or ".dll", or the default shared library
+ *  extension on the current platform, Ruby loads the shared library as a
+ *  Ruby extension.  Otherwise, Ruby tries adding ".rb", ".so", and so on
+ *  to the name until found.  If the file named cannot be found, a LoadError
+ *  will be raised.
+ *
+ *  For Ruby extensions the filename given may use any shared library
+ *  extension.  For example, on Linux the socket extension is "socket.so" and
+ *  <code>require 'socket.dll'</code> will load the socket extension.
+ *
+ *  The absolute path of the loaded file is added to
+ *  <code>$LOADED_FEATURES</code> (<code>$"</code>).  A file will not be
+ *  loaded again if its path already appears in <code>$"</code>.  For example,
+ *  <code>require 'a'; require './a'</code> will not load <code>a.rb</code>
+ *  again.
+ *
+ *    require "my-library.rb"
+ *    require "db-driver"
  */
 
 VALUE