From 13ab96439bcb57ea9dd6703721c08285d19b1ffa Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Thu, 16 Jun 2022 09:56:33 -0500
Subject: [PATCH] [DOC] Small tweaks (#89)

---
 lib/fileutils.rb | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/lib/fileutils.rb b/lib/fileutils.rb
index 74cd595..5aa761e 100644
--- a/lib/fileutils.rb
+++ b/lib/fileutils.rb
@@ -368,6 +368,8 @@ def mkdir(list, mode: nil, noop: nil, verbose: nil)
   #
   # Raises an exception if for any reason a directory cannot be created.
   #
+  # FileUtils.mkpath and FileUtils.makedirs are aliases for FileUtils.mkdir_p.
+  #
   def mkdir_p(list, mode: nil, noop: nil, verbose: nil)
     list = fu_list(list)
     fu_output_message "mkdir -p #{mode ? ('-m %03o ' % mode) : ''}#{list.join ' '}" if verbose
@@ -1161,7 +1163,7 @@ def rm(list, force: nil, noop: nil, verbose: nil)
   #
   #   FileUtils.rm(list, force: true, **kwargs)
   #
-  # Argument +list+ or its elements
+  # Argument +list+ (a single path or an array of paths)
   # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments].
   #
   # See FileUtils.rm for keyword arguments.
@@ -1422,6 +1424,8 @@ def remove_dir(path, force = false)
   # Arguments +a+ and +b+
   # should be {interpretable as a path}[rdoc-ref:FileUtils@Path+Arguments].
   #
+  # FileUtils.identical? and FileUtils.cmp are aliases for FileUtils.compare_file.
+  #
   def compare_file(a, b)
     return false unless File.size(a) == File.size(b)
     File.open(a, 'rb') {|fa|
@@ -1458,8 +1462,8 @@ def compare_stream(a, b)
   end
   module_function :compare_stream
 
-  # Copies a file entry;
-  # see {install(1)}[https://man7.org/linux/man-pages/man1/install.1.html].
+  # Copies a file entry.
+  # See {install(1)}[https://man7.org/linux/man-pages/man1/install.1.html].
   #
   # Arguments +src+ (a single path or an array of paths)
   # and +dest+ (a single path)
@@ -1638,7 +1642,8 @@ def mode_to_s(mode)  #:nodoc:
 
   # 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+:
+  # to the permissions given by +mode+;
+  # returns +list+ if it is an array, <tt>[list]</tt> otherwise:
   #
   # - Modifies each entry that is a regular file using
   #   {File.chmod}[https://docs.ruby-lang.org/en/master/File.html#method-c-chmod].
@@ -1737,7 +1742,8 @@ def chmod_R(mode, list, noop: nil, verbose: nil, force: nil)
 
   # 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+:
+  # to the given +user+ and +group+;
+  # returns +list+ if it is an array, <tt>[list]</tt> otherwise:
   #
   # - Modifies each entry that is a regular file using
   #   {File.chown}[https://docs.ruby-lang.org/en/master/File.html#method-c-chown].
@@ -1863,7 +1869,10 @@ def fu_get_gid(group)   #:nodoc:
   # Updates modification times (mtime) and access times (atime)
   # 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.
+  # returns +list+ if it is an array, <tt>[list]</tt> otherwise.
+  #
+  # By default, creates an empty file for any path to a non-existent entry;
+  # use keyword argument +nocreate+ to raise an exception instead.
   #
   # Argument +list+ or its elements
   # should be {interpretable as paths}[rdoc-ref:FileUtils@Path+Arguments].