[DOC] Enhanced RDoc for copy_entry

lib/fileutils.rb

@@ -607,7 +607,7 @@ def ln_sf(src, dest, noop: nil, verbose: nil)
   #     'src1/dir1/t3.txt',
   #     ]
   #   FileUtils.touch(src_file_paths)
-  #   File.exist?('dest1')
+  #   File.exist?('dest1')             # => true
   #   FileUtils.link_entry('src1', 'dest1')
   #   File.exist?('dest1/dir0/t0.txt') # => true
   #   File.exist?('dest1/dir0/t1.txt') # => true
@@ -777,21 +777,43 @@ def cp_r(src, dest, preserve: nil, noop: nil, verbose: nil,
   end
   module_function :cp_r
 
+  # Recursively copies files from +src+ to +dest+.
   #
-  # Copies a file system entry +src+ to +dest+.
-  # If +src+ is a directory, this method copies its contents recursively.
-  # This method preserves file types, c.f. symlink, directory...
-  # (FIFO, device files and etc. are not supported yet)
-  #
-  # Both of +src+ and +dest+ must be a path name.
-  # +src+ must exist, +dest+ must not exist.
+  # If +src+ is the path to a file, copies +src+ to +dest+:
   #
-  # If +preserve+ is true, this method preserves owner, group, and
-  # modified time.  Permissions are copied regardless +preserve+.
+  #   FileUtils.touch('src0.txt')
+  #   File.exist?('dest0.txt') # => false
+  #   FileUtils.copy_entry('src0.txt', 'dest0.txt')
+  #   File.file?('dest0.txt')  # => true
+  #
+  # If +src+ is a directory, recursively copies +src+ to +dest+:
+  #
+  #   src1
+  #   |-- dir0
+  #   |   |-- src0.txt
+  #   |   `-- src1.txt
+  #   `-- dir1
+  #       |-- src2.txt
+  #       `-- src3.txt
+  #   FileUtils.copy_entry('src1', 'dest1')
+  #   dest1
+  #   |-- dir0
+  #   |   |-- src0.txt
+  #   |   `-- src1.txt
+  #   `-- dir1
+  #       |-- src2.txt
+  #       `-- src3.txt
+  #
+  # The recursive copying preserves file types for regular files,
+  # directories, and symbolic links;
+  # other file types (FIFO streams, device files, etc.) are not supported.
   #
-  # If +dereference_root+ is true, this method dereference tree root.
+  # Keyword arguments:
   #
-  # If +remove_destination+ is true, this method removes each destination file before copy.
+  # - <tt>dereference_root: true</tt> - if +src+ is a symbolic link,
+  #   follows the link.
+  # - <tt>preserve</tt> - preserves file times.
+  # - <tt>remove_destination: true</tt> - removes +dest+ before copying files.
   #
   def copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false)
     if dereference_root