diff --git a/lib/pathname.rb b/lib/pathname.rb
index 37a5a21..1ea4e49 100644
--- a/lib/pathname.rb
+++ b/lib/pathname.rb
@@ -73,9 +73,35 @@ def rmtree(noop: nil, verbose: nil, secure: nil)
 end
 
 class Pathname    # * tmpdir *
-  # Creates a tmp directory and wraps the returned path in a Pathname object.
+  # call-seq:
+  #   Pathname.mktmpdir {|pathname| ... } -> object
+  #   Pathname.mktmpdir -> new_pathname
+  #
+  # Creates:
+  #
+  # - A temporary directory via Dir.mktmpdir.
+  # - A \Pathname object that contains the path to that directory.
+  #
+  # With a block given, calls the block with the pathname;
+  # on block exit, deletes the directory and all its contents;
+  # returns the block's exit value:
+  #
+  #   pathname = Pathname.mktmpdir do |pathname|
+  #     # Do something with the directory.
+  #   end
+  #   Dir.exist?(pathname.to_s) # => false
+  #
+  # With no block given, returns the pathname;
+  # the caller should delete the 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)
   #
-  # See Dir.mktmpdir
   def self.mktmpdir
     require 'tmpdir' unless defined?(Dir.mktmpdir)
     if block_given?