Enhanced RDoc for File (#5849)

Treats:

    #path
    ::stat
    ::lstat
    #lstat
    ::directory?

Also adds section "Example Files" that explains assumptions about example files. I'm using t.txt already, and I'm pretty sure I'll need t.dat (binary data). I don't know whether I'll need t.rus (Russian text).

file.c

@@ -444,21 +444,21 @@ apply2files(int (*func)(const char *, void *), int argc, VALUE *argv, void *arg)
 
 /*
  *  call-seq:
- *     file.path  ->  filename
+ *    path -> filepath
- *     file.to_path  ->  filename
  *
- *  Returns the pathname used to create <i>file</i> as a string. Does
+ *  Returns the string filepath used to create +self+:
- *  not normalize the name.
  *
- *  The pathname may not point to the file corresponding to <i>file</i>.
+ *    f = File.new('t.txt') # => #<File:t.txt>
- *  For instance, the pathname becomes void when the file has been
+      f.path                # => "t.txt"
- *  moved or deleted.
  *
- *  This method raises IOError for a <i>file</i> created using
+ *  Does not normalize the returned filepath:
- *  File::Constants::TMPFILE because they don't have a pathname.
  *
- *     File.new("testfile").path               #=> "testfile"
+ *    f = File.new('../files/t.txt') # => #<File:../files/t.txt>
- *     File.new("/tmp/../tmp/xxx", "w").path   #=> "/tmp/../tmp/xxx"
+      f.path                         # => "../files/t.txt"
+ *
+ *  Raises IOError for a file created using File::Constants::TMPFILE, because it has no filename.
+ *
+ *  File#to_path is an alias for File#path.
  *
  */
 
@@ -1309,11 +1309,11 @@ rb_stat(VALUE file, struct stat *st)
 
 /*
  *  call-seq:
- *     File.stat(file_name)   ->  stat
+ *    File.stat(filepath) ->  stat
  *
- *  Returns a File::Stat object for the named file (see File::Stat).
+ *  Returns a File::Stat object for the file at +filepath+ (see File::Stat):
  *
- *     File.stat("testfile").mtime   #=> Tue Apr 08 12:58:04 CDT 2003
+ *    File.stat('t.txt').class # => File::Stat
  *
  */
 
@@ -1381,15 +1381,14 @@ lstat_without_gvl(const char *path, struct stat *st)
 
 /*
  *  call-seq:
- *     File.lstat(file_name)   -> stat
+ *    File.lstat(filepath) -> stat
  *
- *  Same as File::stat, but does not follow the last symbolic link.
+ *  Like File::stat, but does not follow the last symbolic link;
- *  Instead, reports on the link itself.
+ *  instead, returns a File::Stat object for the link itself.
  *
- *     File.symlink("testfile", "link2test")   #=> 0
+ *    File.symlink('t.txt', 'symlink')
- *     File.stat("testfile").size              #=> 66
+ *    File.stat('symlink').size  # => 47
- *     File.lstat("link2test").size            #=> 8
+ *    File.lstat('symlink').size # => 5
- *     File.stat("link2test").size             #=> 66
  *
  */
 
@@ -1412,16 +1411,16 @@ rb_file_s_lstat(VALUE klass, VALUE fname)
 
 /*
  *  call-seq:
- *     file.lstat   ->  stat
+ *    lstat -> stat
  *
- *  Same as IO#stat, but does not follow the last symbolic link.
+ *  Like File#stat, but does not follow the last symbolic link;
- *  Instead, reports on the link itself.
+ *  instead, returns a File::Stat object for the link itself:
+ *
+ *    File.symlink('t.txt', 'symlink')
+ *    f = File.new('symlink')
+ *    f.stat.size  # => 47
+ *    f.lstat.size # => 11
  *
- *     File.symlink("testfile", "link2test")   #=> 0
- *     File.stat("testfile").size              #=> 66
- *     f = File.new("link2test")
- *     f.lstat.size                            #=> 8
- *     f.stat.size                             #=> 66
  */
 
 static VALUE
@@ -1590,15 +1589,20 @@ rb_access(VALUE fname, int mode)
  * Document-method: directory?
  *
  * call-seq:
- *   File.directory?(file_name)   ->  true or false
+ *   File.directory?(path) -> true or false
  *
- * Returns <code>true</code> if the named file is a directory,
+ * With string +object+ given, returns +true+ if +path+ is a string path
- * or a symlink that points at a directory, and <code>false</code>
+ * leading to a directory, or to a symbolic link to a directory; +false+ otherwise:
- * otherwise.
  *
- * _file_name_ can be an IO object.
+ *   File.directory?('.')              # => true
+ *   File.directory?('foo')            # => false
+ *   File.symlink('.', 'dirlink')      # => 0
+ *   File.directory?('dirlink')        # => true
+ *   File.symlink('t,txt', 'filelink') # => 0
+ *   File.directory?('filelink')       # => false
+ *
+ * Argument +path+ can be an IO object.
  *
- *    File.directory?(".")
  */
 
 VALUE
@@ -6573,6 +6577,34 @@ const char ruby_null_device[] =
  *  may be found in module File::Constants;
  *  an array of their names is returned by <tt>File::Constants.constants</tt>.
  *
+ *  == Example Files
+ *
+ *  Many examples here use these filenames and their corresponding files:
+ *
+ *  - <tt>t.txt</tt>: A text-only file that is assumed to exist via:
+ *
+ *      text = <<~EOT
+ *        First line
+ *        Second line
+ *
+ *        Fourth line
+ *        Fifth line
+ *      EOT
+ *      File.write('t.txt', text)
+ *
+ *  - <tt>t.dat</tt>: A data file that is assumed to exist via:
+ *
+ *      data = "\u9990\u9991\u9992\u9993\u9994"
+ *      f = File.open('t.dat', 'wb:UTF-16')
+ *      f.write(data)
+ *      f.close
+ *
+ *  - <tt>t.rus</tt>: A Russian-language text file that is assumed to exist via:
+ *
+ *      File.write('t.rus', "\u{442 435 441 442}")
+ *
+ *  - <tt>t.tmp</tt>: A file that is assumed _not_ to exist.
+ *
  *  == What's Here
  *
  *  First, what's elsewhere. \Class \File: