* ext/pathname/lib/pathname.rb: Documentation for Pathname.

* ext/pathname/pathname.c: ditto.
  [Bug #6947] [ruby-core:47354]



git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@36950 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 89 insertions, 48 deletions

diff --git a/ext/pathname/lib/pathname.rb b/ext/pathname/lib/pathname.rb
index 4909c2dc23..fba1074320 100644
--- a/ext/pathname/lib/pathname.rb
+++ b/ext/pathname/lib/pathname.rb
@@ -8,8 +8,6 @@
 #
 # For documentation, see class Pathname.
 #
-# <tt>pathname.rb</tt> is distributed with Ruby since 1.8.0.
-#
 
 require 'pathname.so'
 
@@ -29,7 +27,6 @@ class Pathname
     proc {|a, b| a == b}
   end
 
-  # :startdoc:
 
   if File::ALT_SEPARATOR
     SEPARATOR_LIST = "#{Regexp.quote File::ALT_SEPARATOR}#{Regexp.quote File::SEPARATOR}"
@@ -39,6 +36,8 @@ class Pathname
     SEPARATOR_PAT = /#{Regexp.quote File::SEPARATOR}/
   end
 
+  # :startdoc:
+
   # chop_basename(path) -> [pre-basename, basename] or nil
   def chop_basename(path)
     base = File.basename(path)
@@ -78,9 +77,11 @@ class Pathname
   # removed.  The filesystem is not accessed.
   #
   # If +consider_symlink+ is +true+, then a more conservative algorithm is used
-  # to avoid breaking symbolic linkages.  This may retain more <tt>..</tt>
+  # to avoid breaking symbolic linkages.  This may retain more +..+
   # entries than absolutely necessary, but without accessing the filesystem,
-  # this can't be avoided.  See #realpath.
+  # this can't be avoided.
+  #
+  # See Pathname#realpath.
   #
   def cleanpath(consider_symlink=false)
     if consider_symlink
@@ -91,7 +92,7 @@ class Pathname
   end
 
   #
-  # Clean the path simply by resolving and removing excess "." and ".." entries.
+  # Clean the path simply by resolving and removing excess +.+ and +..+ entries.
   # Nothing more, nothing less.
   #
   def cleanpath_aggressive
@@ -179,14 +180,14 @@ class Pathname
   end
   private :cleanpath_conservative
 
-  # #parent returns the parent directory.
+  # Returns the parent directory.
   #
-  # This is same as <tt>self + '..'</tt>.
+  # This is same as <code>self + '..'</code>.
   def parent
     self + '..'
   end
 
-  # #mountpoint? returns +true+ if <tt>self</tt> points to a mountpoint.
+  # Returns +true+ if +self+ points to a mountpoint.
   def mountpoint?
     begin
       stat1 = self.lstat
@@ -199,10 +200,10 @@ class Pathname
   end
 
   #
-  # #root? is a predicate for root directories.  I.e. it returns +true+ if the
+  # Predicate method for root directories.  Returns +true+ if the
   # pathname consists of consecutive slashes.
   #
-  # It doesn't access actual filesystem.  So it may return +false+ for some
+  # It doesn't access the filesystem.  So it may return +false+ for some
   # pathnames which points to roots such as <tt>/usr/..</tt>.
   #
   def root?
@@ -210,12 +211,31 @@ class Pathname
   end
 
   # Predicate method for testing whether a path is absolute.
+  #
   # It returns +true+ if the pathname begins with a slash.
+  #
+  #   p = Pathname.new('/im/sure')
+  #   p.absolute?
+  #       #=> true
+  #
+  #   p = Pathname.new('not/so/sure')
+  #   p.absolute?
+  #       #=> false
   def absolute?
     !relative?
   end
 
-  # The opposite of #absolute?
+  # The opposite of Pathname#absolute?
+  #
+  # It returns +false+ if the pathname begins with a slash.
+  #
+  #   p = Pathname.new('/im/sure')
+  #   p.relative?
+  #       #=> false
+  #
+  #   p = Pathname.new('not/so/sure')
+  #   p.relative?
+  #       #=> true
   def relative?
     path = @path
     while r = chop_basename(path)
@@ -230,6 +250,13 @@ class Pathname
   #   Pathname.new("/usr/bin/ruby").each_filename {|filename| ... }
   #     # yields "usr", "bin", and "ruby".
   #
+  # Returns an Enumerator if no block was given.
+  #
+  #   enum = Pathname.new("/usr/bin/ruby").each_filename
+  #     # ... do stuff ...
+  #   enum.each { |e| ... }
+  #     # yields "usr", "bin", and "ruby".
+  #
   def each_filename # :yield: filename
     return to_enum(__method__) unless block_given?
     _, names = split_names(@path)
@@ -253,9 +280,7 @@ class Pathname
   #     #<Pathname:path/to/some>
   #     #<Pathname:path/to/some/file.rb>
   #
-  # It doesn't access actual filesystem.
-  #
-  # This method is available since 1.8.5.
+  # It doesn't access the filesystem.
   #
   def descend
     vs = []
@@ -280,9 +305,7 @@ class Pathname
   #     #<Pathname:path/to>
   #     #<Pathname:path>
   #
-  # It doesn't access actual filesystem.
-  #
-  # This method is available since 1.8.5.
+  # It doesn't access the filesystem.
   #
   def ascend
     path = @path
@@ -295,8 +318,7 @@ class Pathname
   end
 
   #
-  # Pathname#+ appends a pathname fragment to this one to produce a new Pathname
-  # object.
+  # Appends a pathname fragment to +self+ to produce a new Pathname object.
   #
   #   p1 = Pathname.new("/usr")      # Pathname:/usr
   #   p2 = p1 + "bin/ruby"           # Pathname:/usr/bin/ruby
@@ -352,10 +374,14 @@ class Pathname
   private :plus
 
   #
-  # Pathname#join joins pathnames.
+  # Joins the given pathnames onto +self+ to create a new Pathname object.
   #
-  # <tt>path0.join(path1, ..., pathN)</tt> is the same as
-  # <tt>path0 + path1 + ... + pathN</tt>.
+  #   path0 = Pathname.new("/usr")                # Pathname:/usr
+  #   path0 = path0.join("bin/ruby")              # Pathname:/usr/bin/ruby
+  #       # is the same as
+  #   path1 = Pathname.new("/usr") + "bin/ruby"   # Pathname:/usr/bin/ruby
+  #   path0 == path1
+  #       #=> true
   #
   def join(*args)
     args.unshift self
@@ -372,10 +398,11 @@ class Pathname
 
   #
   # Returns the children of the directory (files and subdirectories, not
-  # recursive) as an array of Pathname objects.  By default, the returned
-  # pathnames will have enough information to access the files.  If you set
-  # +with_directory+ to +false+, then the returned pathnames will contain the
-  # filename only.
+  # recursive) as an array of Pathname objects.
+  #
+  # By default, the returned pathnames will have enough information to access
+  # the files. If you set +with_directory+ to +false+, then the returned
+  # pathnames will contain the filename only.
   #
   # For example:
   #   pn = Pathname("/usr/lib/ruby/1.8")
@@ -386,11 +413,9 @@ class Pathname
   #   pn.children(false)
   #       # -> [ Pathname:English.rb, Pathname:Env.rb, Pathname:abbrev.rb, ... ]
   #
-  # Note that the results never contain the entries <tt>.</tt> and <tt>..</tt> in
+  # Note that the results never contain the entries +.+ and +..+ in
   # the directory because they are not children.
   #
-  # This method has existed since 1.8.1.
-  #
   def children(with_directory=true)
     with_directory = false if @path == '.'
     result = []
@@ -407,9 +432,14 @@ class Pathname
 
   # Iterates over the children of the directory
   # (files and subdirectories, not recursive).
+  #
   # It yields Pathname object for each child.
-  # By default, the yielded pathnames will have enough information to access the files.
-  # If you set +with_directory+ to +false+, then the returned pathnames will contain the filename only.
+  #
+  # By default, the yielded pathnames will have enough information to access
+  # the files.
+  #
+  # If you set +with_directory+ to +false+, then the returned pathnames will
+  # contain the filename only.
   #
   #   Pathname("/usr/local").each_child {|f| p f }
   #   #=> #<Pathname:/usr/local/share>
@@ -431,20 +461,25 @@ class Pathname
   #   #   #<Pathname:src>
   #   #   #<Pathname:man>
   #
+  # Note that the results never contain the entries +.+ and +..+ in
+  # the directory because they are not children.
+  #
+  # See Pathname#children
+  #
   def each_child(with_directory=true, &b)
     children(with_directory).each(&b)
   end
 
   #
-  # #relative_path_from returns a relative path from the argument to the
-  # receiver.  If +self+ is absolute, the argument must be absolute too.  If
-  # +self+ is relative, the argument must be relative too.
+  # Returns a relative path from the given +base_directory+ to the receiver.
   #
-  # #relative_path_from doesn't access the filesystem.  It assumes no symlinks.
+  # If +self+ is absolute, then +base_directory+ must be absolute too.
   #
-  # ArgumentError is raised when it cannot find a relative path.
+  # If +self+ is relative, then +base_directory+ must be relative too.
   #
-  # This method has existed since 1.8.1.
+  # This method doesn't access the filesystem.  It assumes no symlinks.
+  #
+  # ArgumentError is raised when it cannot find a relative path.
   #
   def relative_path_from(base_directory)
     dest_directory = self.cleanpath.to_s
@@ -486,16 +521,18 @@ end
 
 class Pathname    # * Find *
   #
-  # Pathname#find is an iterator to traverse a directory tree in a depth first
-  # manner.  It yields a Pathname for each file under "this" directory.
+  # Iterates over the directory tree in a depth first manner, yielding a
+  # Pathname for each file under "this" directory.
   #
-  # Returns an enumerator if no block is given.
+  # Returns an Enumerator if no block is given.
   #
-  # Since it is implemented by <tt>find.rb</tt>, <tt>Find.prune</tt> can be used
-  # to control the traversal.
+  # Since it is implemented by the standard library module Find, Find.prune can
+  # be used to control the traversal.
   #
-  # If +self+ is <tt>.</tt>, yielded pathnames begin with a filename in the
-  # current directory, not <tt>./</tt>.
+  # If +self+ is +.+, yielded pathnames begin with a filename in the
+  # current directory, not +./+.
+  #
+  # See Find.find
   #
   def find # :yield: pathname
     return to_enum(__method__) unless block_given?
@@ -510,15 +547,19 @@ end
 
 
 class Pathname    # * FileUtils *
-  # See <tt>FileUtils.mkpath</tt>.  Creates a full path, including any
-  # intermediate directories that don't yet exist.
+  # Creates a full path, including any intermediate directories that don't yet
+  # exist.
+  #
+  # See FileUtils.mkpath and FileUtils.mkdir_p
   def mkpath
     require 'fileutils'
     FileUtils.mkpath(@path)
     nil
   end
 
-  # See <tt>FileUtils.rm_r</tt>.  Deletes a directory and all beneath it.
+  # Recursively deletes a directory, including all directories beneath it.
+  #
+  # See FileUtils.rm_r
   def rmtree
     # The name "rmtree" is borrowed from File::Path of Perl.
     # File::Path provides "mkpath" and "rmtree".