[DOC] More on paths and lists (#88)

lib/fileutils.rb

@@ -168,7 +168,7 @@
 # - FileUtils.rm_rf with keyword argument <tt>secure: true</tt>.
 #
 # Finally, this method for moving entries calls \FileUtils.remove_entry_secure
-# if the source and destination are on different devices
+# if the source and destination are on different file systems
 # (which means that the "move" is really a copy and remove):
 #
 # - FileUtils.mv with keyword argument <tt>secure: true</tt>.
@@ -555,21 +555,6 @@ def ln(src, dest, force: nil, noop: nil, verbose: nil)
   #         "tmp1/tmp3/t2.txt",
   #         "tmp1/tmp3/t3.txt"]
   #
-  # If +src+ is an array of paths to files and +dest+ is the path to a directory,
-  # for each path +filepath+ in +src+, creates a link at <tt>dest/filepath</tt>
-  # pointing to that path:
-  #
-  #   FileUtils.rm_r('tmp1')
-  #   Dir.mkdir('tmp1')
-  #   FileUtils.cp_lr(['tmp0/tmp3/t2.txt', 'tmp0/tmp3/t3.txt'], 'tmp1')
-  #   Dir.glob('**/*.txt')
-  #   # => ["tmp0/tmp2/t0.txt",
-  #        "tmp0/tmp2/t1.txt",
-  #        "tmp0/tmp3/t2.txt",
-  #        "tmp0/tmp3/t3.txt",
-  #        "tmp1/t2.txt",
-  #        "tmp1/t3.txt"]
-  #
   # If +src+ and +dest+ are both paths to directories,
   # creates links <tt>dest/src</tt> and descendents
   # pointing to +src+ and its descendents:
@@ -586,6 +571,21 @@ def ln(src, dest, force: nil, noop: nil, verbose: nil)
   #        "tmp1/tmp0/tmp3/t2.txt",
   #        "tmp1/tmp0/tmp3/t3.txt"]
   #
+  # If +src+ is an array of paths to files and +dest+ is the path to a directory,
+  # for each path +filepath+ in +src+, creates a link at <tt>dest/filepath</tt>
+  # pointing to that path:
+  #
+  #   FileUtils.rm_r('tmp1')
+  #   Dir.mkdir('tmp1')
+  #   FileUtils.cp_lr(['tmp0/tmp3/t2.txt', 'tmp0/tmp3/t3.txt'], 'tmp1')
+  #   Dir.glob('**/*.txt')
+  #   # => ["tmp0/tmp2/t0.txt",
+  #        "tmp0/tmp2/t1.txt",
+  #        "tmp0/tmp3/t2.txt",
+  #        "tmp0/tmp3/t3.txt",
+  #        "tmp1/t2.txt",
+  #        "tmp1/t3.txt"]
+  #
   # Keyword arguments:
   #
   # - <tt>dereference_root: false</tt> - if +src+ is a symbolic link,
@@ -621,7 +621,7 @@ def cp_lr(src, dest, noop: nil, verbose: nil,
   # and +dest+ (a single path)
   # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments].
   #
-  # When +src+ is the path to an existing file:
+  # If +src+ is the path to an existing file:
   #
   # - When +dest+ is the path to a non-existent file,
   #   creates a symbolic link at +dest+ pointing to +src+:
@@ -643,15 +643,15 @@ def cp_lr(src, dest, noop: nil, verbose: nil,
   #
   #     FileUtils.ln_s('src1.txt', 'dest1.txt') # Raises Errno::EEXIST.
   #
-  # When +dest+ is the path to a directory,
+  # If +dest+ is the path to a directory,
   # creates a symbolic link at <tt>dest/src</tt> pointing to +src+:
   #
   #   FileUtils.touch('src2.txt')
   #   FileUtils.mkdir('destdir2')
   #   FileUtils.ln_s('src2.txt', 'destdir2')
   #   File.symlink?('destdir2/src2.txt') # => true
   #
-  # When +src+ is an array of paths to existing files and +dest+ is a directory,
+  # If +src+ is an array of paths to existing files and +dest+ is a directory,
   # for each child +child+ in +src+ creates a symbolic link <tt>dest/child</tt>
   # pointing to +child+:
   #
@@ -751,7 +751,7 @@ def link_entry(src, dest, dereference_root = false, remove_destination = false)
   end
   module_function :link_entry
 
-  # Copies files from +src+ to +dest+.
+  # Copies files.
   #
   # Arguments +src+ (a single path or an array of paths)
   # and +dest+ (a single path)
@@ -1018,14 +1018,15 @@ def copy_stream(src, dest)
   end
   module_function :copy_stream
 
-  # Moves files from +src+ (a single path or an array of paths)
-  # to +dest+ (a single path).
-  # If +src+ and +dest+ are on different devices,
-  # first copies, then removes +src+.
+  # Moves entries.
   #
-  # Arguments +src+ and +dest+
+  # Arguments +src+ (a single path or an array of paths)
+  # and +dest+ (a single path)
   # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments].
   #
+  # If +src+ and +dest+ are on different file systems,
+  # first copies, then removes +src+.
+  #
   # May cause a local vulnerability if not called with keyword argument
   # <tt>secure: true</tt>;
   # see {Avoiding the TOCTTOU Vulnerability}[rdoc-ref:FileUtils@Avoiding+the+TOCTTOU+Vulnerability].
@@ -1066,7 +1067,7 @@ def copy_stream(src, dest)
   # Keyword arguments:
   #
   # - <tt>force: true</tt> - if the move includes removing +src+
-  #   (that is, if +src+ and +dest+ are on different devices),
+  #   (that is, if +src+ and +dest+ are on different file systems),
   #   ignores raised exceptions of StandardError and its descendants.
   # - <tt>noop: true</tt> - does not move files.
   # - <tt>secure: true</tt> - removes +src+ securely;
@@ -1457,11 +1458,12 @@ def compare_stream(a, b)
   end
   module_function :compare_stream
 
-  # Copies the file entry at path +src+ to the entry at path +dest+;
+  # Copies a file entry;
   # see {install(1)}[https://man7.org/linux/man-pages/man1/install.1.html].
   #
-  # Arguments +src+ and +dest+
-  # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments].
+  # Arguments +src+ (a single path or an array of paths)
+  # and +dest+ (a single path)
+  # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments];
   #
   # If the entry at +dest+ does not exist, copies from +src+ to +dest+:
   #
@@ -1485,6 +1487,16 @@ def compare_stream(a, b)
   #   FileUtils.install('src2.txt', 'dest2')
   #   File.read('dest2/src2.txt') # => "aaa\n"
   #
+  # If +src+ is an array of paths and +dest+ points to a directory,
+  # copies each path +path+ in +src+ to <tt>dest/path</tt>:
+  #
+  #   File.file?('src3.txt') # => true
+  #   File.file?('src3.dat') # => true
+  #   FileUtils.mkdir('dest3')
+  #   FileUtils.install(['src3.txt', 'src3.dat'], 'dest3')
+  #   File.file?('dest3/src3.txt') # => true
+  #   File.file?('dest3/src3.dat') # => true
+  #
   # Keyword arguments:
   #
   # - <tt>group: <i>group</i></tt> - changes the group if not +nil+,