File rdoc (#5438)

Treats:

    File introduction
    File.open
    File.new

file.c

@@ -6511,36 +6511,67 @@ const char ruby_null_device[] =
     ;
 
 /*
- *  A File is an abstraction of any file object accessible by the
- *  program and is closely associated with class IO.  File includes
- *  the methods of module FileTest as class methods, allowing you to
- *  write (for example) <code>File.exist?("foo")</code>.
+ *  A \File object is a representation of a file in the underlying platform.
  *
- *  In the description of File methods,
- *  <em>permission bits</em> are a platform-specific
- *  set of bits that indicate permissions of a file. On Unix-based
- *  systems, permissions are viewed as a set of three octets, for the
- *  owner, the group, and the rest of the world. For each of these
- *  entities, permissions may be set to read, write, or execute the
- *  file:
+ *  \Class \File extends module FileTest, supporting such singleton methods
+ *  as <tt>File.exist?</tt>.
  *
- *  The permission bits <code>0644</code> (in octal) would thus be
- *  interpreted as read/write for owner, and read-only for group and
- *  other. Higher-order bits may also be used to indicate the type of
- *  file (plain, directory, pipe, socket, and so on) and various other
- *  special features. If the permissions are for a directory, the
- *  meaning of the execute bit changes; when set the directory can be
- *  searched.
+ *  == \File Permissions
  *
- *  On non-Posix operating systems, there may be only the ability to
- *  make a file read-only or read-write. In this case, the remaining
- *  permission bits will be synthesized to resemble typical values. For
- *  instance, on Windows NT the default permission bits are
- *  <code>0644</code>, which means read/write for owner, read-only for
- *  all others. The only change that can be made is to make the file
+ *  A \File object has _permissions_, an octal integer representing
+ *  the permissions of an actual file in the underlying platform.
+ *
+ *  Note that file permissions are quite different from the _mode_
+ *  of a file stream (\File object).
+ *  See {IO Modes}[#class-IO-label-Modes].
+ *
+ *  In a \File object, the permissions are available thus,
+ *  where method +mode+, despite its name, returns permissions:
+ *
+ *    f = File.new('t.txt')
+ *    f.lstat.mode.to_s(8) # => "100644"
+ *
+ *  On a Unix-based operating system,
+ *  the three low-order octal digits represent the permissions
+ *  for owner (6), group (4), and world (4).
+ *  The triplet of bits in each octal digit represent, respectively,
+ *  read, write, and execute permissions.
+ *
+ *  Permissions <tt>0644</tt> thus represent read-write access for owner
+ *  and read-only access for group and world.
+ *  See man pages {open(2)}[https://www.unix.com/man-page/bsd/2/open]
+ *  and {chmod(2)}[https://www.unix.com/man-page/bsd/2/chmod].
+ *
+ *  For a directory, the meaning of the execute bit changes:
+ *  when set, the directory can be searched.
+ *
+ *  Higher-order bits in permissions may indicate the type of file
+ *  (plain, directory, pipe, socket, etc.) and various other special features.
+ *
+ *  On non-Posix operating systems, permissions may include only read-only or read-write,
+ *  in which case, the remaining permission will resemble typical values.
+ *  On Windows, for instance, the default permissions are <code>0644</code>;
+ *  The only change that can be made is to make the file
  *  read-only, which is reported as <code>0444</code>.
  *
- *  Various constants for the methods in File can be found in File::Constants.
+ *  For a method that actually creates a file in the underlying platform
+ *  (as opposed to merely creating a \File object),
+ *  permissions may be specified:
+ *
+ *    File.new('t.tmp', File::CREAT, 0644)
+ *    File.new('t.tmp', File::CREAT, 0444)
+ *
+ *  Permissions may also be changed:
+ *
+ *    f = File.new('t.tmp', File::CREAT, 0444)
+ *    f.chmod(0644)
+ *    f.chmod(0444)
+ *
+ *  == \File Constants
+ *
+ *  Various constants for use in \File and \IO methods
+ *  may be found in module File::Constants;
+ *  an array of their names is returned by <tt>File::Constants.constants</tt>.
  *
  *  == What's Here
  *

io.c

@@ -7631,26 +7631,20 @@ rb_open_file(int argc, const VALUE *argv, VALUE io)
     return io;
 }
 
-
 /*
  *  Document-method: File::open
  *
  *  call-seq:
- *     File.open(filename, mode="r" [, opt])                 -> file
- *     File.open(filename [, mode [, perm]] [, opt])         -> file
- *     File.open(filename, mode="r" [, opt]) {|file| block } -> obj
- *     File.open(filename [, mode [, perm]] [, opt]) {|file| block } -> obj
+ *    File.open(path, mode = 'r', perm = 0666, **opts]) -> file
+ *    File.open(path, mode = 'r', perm = 0666, **opts]) {|f| ... } -> object
  *
- *  With no associated block, File.open is a synonym for
- *  File.new. If the optional code block is given, it will
- *  be passed the opened +file+ as an argument and the File object will
- *  automatically be closed when the block terminates.  The value of the block
- *  will be returned from File.open.
+ *  Creates a new \File object, via File.new with the given arguments.
  *
- *  If a file is being created, its initial permissions may be set using the
- *  +perm+ parameter.  See File.new for further discussion.
+ *  With no block given, returns the \File object.
+ *
+ *  With a block given, calls the block with the \File object
+ *  and returns the block's value.
  *
- *  See IO.new for a description of the +mode+ and +opt+ parameters.
  */
 
 /*
@@ -9056,27 +9050,38 @@ rb_io_set_encoding_by_bom(VALUE io)
 
 /*
  *  call-seq:
- *     File.new(filename, mode="r" [, opt])            -> file
- *     File.new(filename [, mode [, perm]] [, opt])    -> file
+ *    File.new(path, mode = 'r', perm = 0666, **opts) -> file
  *
- *  Opens the file named by +filename+ according to the given +mode+ and
- *  returns a new File object.
+ *  Opens the file at the given +path+ according to the given +mode+;
+ *  creates and returns a new \File object for that file.
  *
- *  See IO.new for a description of +mode+ and +opt+.
- *
- *  If a file is being created, permission bits may be given in +perm+.  These
- *  mode and permission bits are platform dependent; on Unix systems, see
- *  open(2) and chmod(2) man pages for details.
- *
- *  The new File object is buffered mode (or non-sync mode), unless
+ *  The new \File object is buffered mode (or non-sync mode), unless
  *  +filename+ is a tty.
- *  See IO#flush, IO#fsync, IO#fdatasync, and IO#sync= about sync mode.
+ *  See IO#flush, IO#fsync, IO#fdatasync, and IO#sync=.
  *
- *  === Examples
+ *  Argument +path+ must be a valid file path:
+ *
+ *    File.new('/etc/fstab')
+ *    File.new('t.txt')
+ *
+ *  Optional argument +mode+ (defaults to 'r') must specify a valid mode
+ *  see {\IO Modes}[#class-IO-label-Modes]:
+ *
+ *    File.new('t.tmp', 'w')
+ *    File.new('t.tmp', File::RDONLY)
+ *
+ *  Optional argument +perm+ (defaults to 0666) must specify valid permissions
+ *  see {File Permissions}[#class-File-label-Permissions]:
+ *
+ *    File.new('t.tmp', File::CREAT, 0644)
+ *    File.new('t.tmp', File::CREAT, 0444)
+ *
+ *  Optional argument +opts+ must specify valid open options
+ *  see {IO Open Options}[#class-IO-label-Open+Options]:
+ *
+ *    File.new('t.tmp', autoclose: true)
+ *    File.new('t.tmp', internal_encoding: nil)
  *
- *    f = File.new("testfile", "r")
- *    f = File.new("newfile",  "w+")
- *    f = File.new("newfile", File::CREAT|File::TRUNC|File::RDWR, 0644)
  */
 
 static VALUE