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

* More on paths and lists

Author: BurdetteLamar

lib/fileutils.rb

@@ -336,7 +336,7 @@ def mkdir(list, mode: nil, noop: nil, verbose: nil)
 
   #
   # Creates directories at the paths in the given +list+
-  # (an array of strings or a single string),
+  # (a single path or an array of paths),
   # also creating ancestor directories as needed;
   # returns +list+ if it is an array, <tt>[list]</tt> otherwise.
   #
@@ -412,7 +412,7 @@ def fu_mkdir(path, mode)   #:nodoc:
 
   #
   # Removes directories at the paths in the given +list+
-  # (an array of strings or a single string);
+  # (a single path or an array of paths);
   # returns +list+, if it is an array, <tt>[list]</tt> otherwise.
   #
   # Argument +list+ or its elements
@@ -464,7 +464,8 @@ def rmdir(list, parents: nil, noop: nil, verbose: nil)
 
   # Creates {hard links}[https://en.wikipedia.org/wiki/Hard_link].
   #
-  # 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].
   #
   # When +src+ is the path to an existing file
@@ -531,7 +532,8 @@ def ln(src, dest, force: nil, noop: nil, verbose: nil)
 
   # Creates {hard links}[https://en.wikipedia.org/wiki/Hard_link].
   #
-  # 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+ is the path to a directory and +dest+ does not exist,
@@ -615,7 +617,8 @@ def cp_lr(src, dest, noop: nil, verbose: nil,
 
   # Creates {symbolic links}[https://en.wikipedia.org/wiki/Symbolic_link].
   #
-  # 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].
   #
   # When +src+ is the path to an existing file:
@@ -750,7 +753,8 @@ def link_entry(src, dest, dereference_root = false, remove_destination = false)
 
   # Copies files from +src+ to +dest+.
   #
-  # 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+ is the path to a file and +dest+ is not the path to a directory,
@@ -991,7 +995,8 @@ def copy_stream(src, dest)
   end
   module_function :copy_stream
 
-  # Moves files from +src+ to +dest+.
+  # 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+.
   #
@@ -1087,7 +1092,8 @@ def mv(src, dest, force: nil, noop: nil, verbose: nil, secure: nil)
   alias move mv
   module_function :move
 
-  # Removes entries at the paths in the given +list+;
+  # Removes entries at the paths in the given +list+
+  # (a single path or an array of paths)
   # returns +list+, if it is an array, <tt>[list]</tt> otherwise.
   #
   # Argument +list+ or its elements
@@ -1147,7 +1153,7 @@ def rm_f(list, noop: nil, verbose: nil)
   module_function :safe_unlink
 
   # Removes entries at the paths in the given +list+
-  # (an array of strings or a single string);
+  # (a single path or an array of paths);
   # returns +list+, if it is an array, <tt>[list]</tt> otherwise.
   #
   # Argument +list+ or its elements
@@ -1596,6 +1602,7 @@ def mode_to_s(mode)  #:nodoc:
   private_module_function :mode_to_s
 
   # Changes permissions on the entries at the paths given in +list+
+  # (a single path or an array of paths)
   # to the permissions given by +mode+:
   #
   # - Modifies each entry that is a regular file using
@@ -1694,6 +1701,7 @@ def chmod_R(mode, list, noop: nil, verbose: nil, force: nil)
   module_function :chmod_R
 
   # Changes the owner and group on the entries at the paths given in +list+
+  # (a single path or an array of paths)
   # to the given +user+ and +group+:
   #
   # - Modifies each entry that is a regular file using
@@ -1818,7 +1826,8 @@ def fu_get_gid(group)   #:nodoc:
   private_module_function :fu_get_gid
 
   # Updates modification times (mtime) and access times (atime)
-  # of the entries given by the paths in +list+;
+  # of the entries given by the paths in +list+
+  # (a single path or an array of paths);
   # by default, creates an empty file for any path to a non-existent entry.
   #
   # Argument +list+ or its elements