1 files changed, 94 insertions, 11 deletions

diff --git a/lib/pathname.rb b/lib/pathname.rb
index a0da5ed93f..0e51e1fdf6 100644
--- a/lib/pathname.rb
+++ b/lib/pathname.rb
@@ -9,22 +9,77 @@
 #
 # For documentation, see class Pathname.
 #
+class Pathname
 
-class Pathname    # * Find *
+  # :markup: markdown
   #
-  # Iterates over the directory tree in a depth first manner, yielding a
-  # Pathname for each file under "this" directory.
+  # call-seq:
+  #   Pathname.find(ignore_error: true) -> nil
   #
-  # Returns an Enumerator if no block is given.
+  # With a block given, performs a depth-first traversal of the path in `self`;
+  # calls the block with each found path:
   #
-  # Since it is implemented by the standard library module Find, Find.prune can
-  # be used to control the traversal.
+  # ```ruby
+  # paths = []
+  # Pathname('lib').find {|path| paths << path }
+  # paths.size  # => 909
+  # paths.take(3)
+  # # =>
+  # # [#<Pathname:lib>,
+  # #  #<Pathname:lib/English.gemspec>,
+  # #  #<Pathname:lib/English.rb>]
+  # ```
   #
-  # If +self+ is +.+, yielded pathnames begin with a filename in the
-  # current directory, not +./+.
+  # When `self` contains `'.'`, the found paths omit the leading `'./'`:
   #
-  # See Find.find
+  # ```ruby
+  # paths = []
+  # Dir.chdir('lib') do
+  #   Pathname('.').find {|path| paths << path }
+  # end
+  # paths.take(3)
+  # # # =>
+  # # [#<Pathname:.>,
+  # #  #<Pathname:English.gemspec>,
+  # #  #<Pathname:English.rb>]
+  # ```
   #
+  # This method calls method Find.find;
+  # therefore method Find.prune may be used in the block:
+  #
+  # ```ruby
+  # files = []
+  # Pathname('.').find do |path|
+  #   Find.prune if File.basename(path) == 'test'
+  #   next unless File.file?(path) && File.extname(path) == '.rb'
+  #   files << path
+  # end
+  # files.size # => 6690
+  # files.take(3)
+  # # # =>
+  # # [#<Pathname:KNOWNBUGS.rb>,
+  # #  #<Pathname:array.rb>,
+  # #  #<Pathname:ast.rb>]
+  # ```
+  #
+  # Raises an exception if the path in `self` cannot be read.
+  #
+  # When keyword argument `ignore_error` is given as `true` (the default),
+  # certain exceptions during traversal are ignored (i.e., silently rescued):
+  # Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP, Errno::ENAMETOOLONG, Errno::EINVAL;
+  # when given as `false`, no exceptions are rescued.
+  #
+  # Note that these exceptions may be ignored only in `Pathname#find` traversal code;
+  # an exception raised before traversal begins,
+  # or raised while in the block is not ignored.
+  # Each of the calls below raises an Errno::ENOENT exception that is not ignored:
+  #
+  # ```ruby
+  # Pathname('nosuch').find { }
+  # Pathname('lib').find {|entry| raise Errno::ENOENT }
+  # ```
+  #
+  # With no block given, returns a new Enumerator.
   def find(ignore_error: true) # :yield: pathname
     return to_enum(__method__, ignore_error: ignore_error) unless block_given?
     require 'find'
@@ -40,6 +95,8 @@ end
 class Pathname    # * FileUtils *
   # Recursively deletes a directory, including all directories beneath it.
   #
+  # Note that you need to require 'pathname' to use this method.
+  #
   # See FileUtils.rm_rf
   def rmtree(noop: nil, verbose: nil, secure: nil)
     # The name "rmtree" is borrowed from File::Path of Perl.
@@ -51,9 +108,35 @@ class Pathname    # * FileUtils *
 end
 
 class Pathname    # * tmpdir *
-  # Creates a tmp directory and wraps the returned path in a Pathname object.
+  # call-seq:
+  #   Pathname.mktmpdir -> new_pathname
+  #   Pathname.mktmpdir {|pathname| ... } -> object
+  #
+  # Creates:
+  #
+  # - A temporary directory via Dir.mktmpdir.
+  # - A \Pathname object that contains the path to that directory.
+  #
+  # With no block given, returns the created pathname;
+  # the caller should delete the created directory when it is no longer needed
+  # (FileUtils.rm_r is a convenient method for the deletion):
+  #
+  #   pathname = Pathname.mktmpdir
+  #   dirpath = pathname.to_s
+  #   Dir.exist?(dirpath) # => true
+  #   # Do something with the directory.
+  #   require 'fileutils'
+  #   FileUtils.rm_r(dirpath)
+  #
+  # With a block given, calls the block with the created pathname;
+  # on block exit, automatically deletes the created directory and all its contents;
+  # returns the block's exit value:
   #
-  # See Dir.mktmpdir
+  #   pathname = Pathname.mktmpdir do |p|
+  #     # Do something with the directory.
+  #     p
+  #   end
+  #   Dir.exist?(pathname.to_s) # => false
   def self.mktmpdir
     require 'tmpdir' unless defined?(Dir.mktmpdir)
     if block_given?