* file.c (File#expand_path): [DOC] improve documentation of File#expand_path.

Based on patch by Prathamesh Sonpatki. [ruby-core:57734] [Bug #9002]

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

ChangeLog

@@ -1,3 +1,8 @@
+Tue Oct 22 16:57:48 2013  Benoit Daloze  <eregontp@gmail.com>
+
+	* file.c (File#expand_path): [DOC] improve documentation of File#expand_path.
+	  Based on patch by Prathamesh Sonpatki. [ruby-core:57734] [Bug #9002]
+
 Tue Oct 22 15:59:51 2013  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 	* dir.c (glob_helper): don't skip current directories if FNM_DOTMATCH

file.c

@@ -3432,7 +3432,18 @@ rb_file_expand_path_fast(VALUE fname, VALUE dname)
  *  user's home directory.
  *
  *     File.expand_path("~oracle/bin")           #=> "/home/oracle/bin"
- *     File.expand_path("../../bin", "/tmp/x")   #=> "/bin"
+ *
+ *  A simple example of using <i>dir_string</i> is as follows.
+ *     File.expand_path("ruby", "/usr/bin")      #=> "/usr/bin/ruby"
+ *
+ *  A more complex example which also resolves parent directory is as follows.
+ *  Suppose we are in bin/mygem and want the absolute path of lib/mygem.rb.
+ *
+ *     File.expand_path("../../lib/mygem.rb", __FILE__)
+ *     #=> ".../path/to/project/lib/mygem.rb"
+ *
+ *  So first it resolves the parent of __FILE__, that is bin/, then go to the
+ *  parent, the root of the project and appends +lib/mygem.rb+.
  */
 
 VALUE