* 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

2 files changed, 314 insertions, 148 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".
diff --git a/ext/pathname/pathname.c b/ext/pathname/pathname.c
index f890019cf9..dd1c5f8878 100644
--- a/ext/pathname/pathname.c
+++ b/ext/pathname/pathname.c
@@ -22,7 +22,7 @@ set_strpath(VALUE obj, VALUE val)
 
 /*
  * Create a Pathname object from the given String (or String-like object).
- * If +path+ contains a NUL character (<tt>\0</tt>), an ArgumentError is raised.
+ * If +path+ contains a NULL character (<tt>\0</tt>), an ArgumentError is raised.
  */
 static VALUE
 path_initialize(VALUE self, VALUE arg)
@@ -46,6 +46,14 @@ path_initialize(VALUE self, VALUE arg)
     return self;
 }
 
+/*
+ * call-seq:
+ *   pathname.freeze -> obj
+ *
+ * Freezes this Pathname.
+ *
+ * See Object.freeze.
+ */
 static VALUE
 path_freeze(VALUE self)
 {
@@ -54,6 +62,14 @@ path_freeze(VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   pathname.taint -> obj
+ *
+ * Taints this Pathname.
+ *
+ * See Object.taint.
+ */
 static VALUE
 path_taint(VALUE self)
 {
@@ -62,6 +78,14 @@ path_taint(VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   pathname.untaint -> obj
+ *
+ * Untaints this Pathname.
+ *
+ * See Object.untaint.
+ */
 static VALUE
 path_untaint(VALUE self)
 {
@@ -84,7 +108,18 @@ path_eq(VALUE self, VALUE other)
 }
 
 /*
- *  Provides for comparing pathnames, case-sensitively.
+ *  Provides a case-sensitive comparison operator for pathnames.
+ *
+ *	Pathname.new('/usr') <=> Pathname.new('/usr/bin')
+ *	    #=> -1
+ *	Pathname.new('/usr/bin') <=> Pathname.new('/usr/bin')
+ *	    #=> 0
+ *	Pathname.new('/usr/bin') <=> Pathname.new('/USR/BIN')
+ *	    #=> 1
+ *
+ *  It will return +-1+, +0+ or +1+ depending on the value of the left argument
+ *  relative to the right argument. Or it will return +nil+ if the arguments
+ *  are not comparable.
  */
 static VALUE
 path_cmp(VALUE self, VALUE other)
@@ -153,6 +188,10 @@ path_inspect(VALUE self)
 
 /*
  * Return a pathname which is substituted by String#sub.
+ *
+ *	path1 = Pathname.new('/usr/bin/perl')
+ *	path1.sub('perl', 'ruby')
+ *	    #=> #<Pathname:/usr/bin/ruby>
  */
 static VALUE
 path_sub(int argc, VALUE *argv, VALUE self)
@@ -169,10 +208,12 @@ path_sub(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * Return a pathname which the extension of the basename is substituted by
- * <i>repl</i>.
+ * Return a pathname with +repl+ added as a suffix to the basename.
  *
- * If self has no extension part, <i>repl</i> is appended.
+ * If self has no extension part, +repl+ is appended.
+ *
+ *	Pathname.new('/usr/bin/shutdown').sub_ext('.rb')
+ *	    #=> #<Pathname:/usr/bin/shutdown.rb>
  */
 static VALUE
 path_sub_ext(VALUE self, VALUE repl)
@@ -202,8 +243,10 @@ path_sub_ext(VALUE self, VALUE repl)
 /* Facade for File */
 
 /*
- * Returns the real (absolute) pathname of +self+ in the actual
- * filesystem not containing symlinks or useless dots.
+ * Returns the real (absolute) pathname for +self+ in the actual
+ * filesystem.
+ *
+ * Does not contain symlinks or useless dots, +..+ and +.+.
  *
  * All components of the pathname must exist when this method is
  * called.
@@ -220,7 +263,8 @@ path_realpath(int argc, VALUE *argv, VALUE self)
 
 /*
  * Returns the real (absolute) pathname of +self+ in the actual filesystem.
- * The real pathname doesn't contain symlinks or useless dots.
+ *
+ * Does not contain symlinks or useless dots, +..+ and +.+.
  *
  * The last component of the real pathname can be nonexistent.
  */
@@ -241,10 +285,7 @@ path_realdirpath(int argc, VALUE *argv, VALUE self)
  *   pathname.each_line(sep, limit [, open_args]) {|line| block } -> nil
  *   pathname.each_line(...)                                      -> an_enumerator
  *
- * #each_line iterates over the line in the file.  It yields a String object
- * for each line.
- *
- * This method is availabel since 1.8.1.
+ * Iterates over each line in the file and yields a String object for each.
  */
 static VALUE
 path_each_line(int argc, VALUE *argv, VALUE self)
@@ -267,8 +308,9 @@ path_each_line(int argc, VALUE *argv, VALUE self)
  *   pathname.read([length [, offset]]) -> string
  *   pathname.read([length [, offset]], open_args) -> string
  *
- * See <tt>IO.read</tt>.  Returns all data from the file, or the first +N+ bytes
- * if specified.
+ * Returns all data from the file, or the first +N+ bytes if specified.
+ *
+ * See IO.read.
  *
  */
 static VALUE
@@ -286,8 +328,9 @@ path_read(int argc, VALUE *argv, VALUE self)
  * call-seq:
  *   pathname.binread([length [, offset]]) -> string
  *
- * See <tt>IO.binread</tt>.  Returns all the bytes from the file, or the first +N+
- * if specified.
+ * Returns all the bytes from the file, or the first +N+ if specified.
+ *
+ * See IO.binread.
  *
  */
 static VALUE
@@ -307,7 +350,9 @@ path_binread(int argc, VALUE *argv, VALUE self)
  *   pathname.readlines(limit [, open_args])      -> array
  *   pathname.readlines(sep, limit [, open_args]) -> array
  *
- * See <tt>IO.readlines</tt>.  Returns all the lines from the file.
+ * Returns all the lines from the file.
+ *
+ * See IO.readlines.
  *
  */
 static VALUE
@@ -325,7 +370,7 @@ path_readlines(int argc, VALUE *argv, VALUE self)
  * call-seq:
  *   pathname.sysopen([mode, [perm]])  -> fixnum
  *
- * See <tt>IO.sysopen</tt>.
+ * See IO.sysopen.
  *
  */
 static VALUE
@@ -340,7 +385,12 @@ path_sysopen(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * See <tt>File.atime</tt>.  Returns last access time.
+ * call-seq:
+ *   pathname.atime	-> time
+ *
+ * Returns the last access time for the file.
+ *
+ * See File.atime.
  */
 static VALUE
 path_atime(VALUE self)
@@ -349,7 +399,12 @@ path_atime(VALUE self)
 }
 
 /*
- * See <tt>File.ctime</tt>.  Returns last (directory entry, not file) change time.
+ * call-seq:
+ *   pathname.ctime	-> time
+ *
+ * Returns the last change time, using directory information, not the file itself.
+ *
+ * See File.ctime.
  */
 static VALUE
 path_ctime(VALUE self)
@@ -358,7 +413,12 @@ path_ctime(VALUE self)
 }
 
 /*
- * See <tt>File.mtime</tt>.  Returns last modification time.
+ * call-seq:
+ *   pathname.mtime	-> time
+ *
+ * Returns the last modified time of the file.
+ *
+ * See File.mtime.
  */
 static VALUE
 path_mtime(VALUE self)
@@ -367,7 +427,12 @@ path_mtime(VALUE self)
 }
 
 /*
- * See <tt>File.chmod</tt>.  Changes permissions.
+ * call-seq:
+ *   pathname.chmod	-> integer
+ *
+ * Changes file permissions.
+ *
+ * See File.chmod.
  */
 static VALUE
 path_chmod(VALUE self, VALUE mode)
@@ -376,7 +441,12 @@ path_chmod(VALUE self, VALUE mode)
 }
 
 /*
- * See <tt>File.lchmod</tt>.
+ * call-seq:
+ *   pathname.lchmod	-> integer
+ *
+ * Same as Pathname.chmod, but does not follow symbolic links.
+ *
+ * See File.lchmod.
  */
 static VALUE
 path_lchmod(VALUE self, VALUE mode)
@@ -385,7 +455,12 @@ path_lchmod(VALUE self, VALUE mode)
 }
 
 /*
- * See <tt>File.chown</tt>.  Change owner and group of file.
+ * call-seq:
+ *   pathname.chown	-> integer
+ *
+ * Change owner and group of the file.
+ *
+ * See File.chown.
  */
 static VALUE
 path_chown(VALUE self, VALUE owner, VALUE group)
@@ -394,7 +469,12 @@ path_chown(VALUE self, VALUE owner, VALUE group)
 }
 
 /*
- * See <tt>File.lchown</tt>.
+ * call-seq:
+ *   pathname.lchown	-> integer
+ *
+ * Same as Pathname.chown, but does not follow symbolic links.
+ *
+ * See File.lchown.
  */
 static VALUE
 path_lchown(VALUE self, VALUE owner, VALUE group)
@@ -407,8 +487,9 @@ path_lchown(VALUE self, VALUE owner, VALUE group)
  *    pathname.fnmatch(pattern, [flags])        -> string
  *    pathname.fnmatch?(pattern, [flags])       -> string
  *
- * See <tt>File.fnmatch</tt>.  Return +true+ if the receiver matches the given
- * pattern.
+ * Return +true+ if the receiver matches the given pattern.
+ *
+ * See File.fnmatch.
  */
 static VALUE
 path_fnmatch(int argc, VALUE *argv, VALUE self)
@@ -422,8 +503,12 @@ path_fnmatch(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * See <tt>File.ftype</tt>.  Returns "type" of file ("file", "directory",
- * etc).
+ * call-seq:
+ *   pathname.ftype	-> string
+ *
+ * Returns "type" of file ("file", "directory", etc).
+ *
+ * See File.ftype.
  */
 static VALUE
 path_ftype(VALUE self)
@@ -435,7 +520,9 @@ path_ftype(VALUE self)
  * call-seq:
  *   pathname.make_link(old)
  *
- * See <tt>File.link</tt>.  Creates a hard link at _pathname_.
+ * Creates a hard link at _pathname_.
+ *
+ * See File.link.
  */
 static VALUE
 path_make_link(VALUE self, VALUE old)
@@ -444,7 +531,9 @@ path_make_link(VALUE self, VALUE old)
 }
 
 /*
- * See <tt>File.open</tt>.  Opens the file for reading or writing.
+ * Opens the file for reading or writing.
+ *
+ * See File.open.
  */
 static VALUE
 path_open(int argc, VALUE *argv, VALUE self)
@@ -463,7 +552,9 @@ path_open(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * See <tt>File.readlink</tt>.  Read symbolic link.
+ * Read symbolic link.
+ *
+ * See File.readlink.
  */
 static VALUE
 path_readlink(VALUE self)
@@ -474,7 +565,9 @@ path_readlink(VALUE self)
 }
 
 /*
- * See <tt>File.rename</tt>.  Rename the file.
+ * Rename the file.
+ *
+ * See File.rename.
  */
 static VALUE
 path_rename(VALUE self, VALUE to)
@@ -483,7 +576,9 @@ path_rename(VALUE self, VALUE to)
 }
 
 /*
- * See <tt>File.stat</tt>.  Returns a <tt>File::Stat</tt> object.
+ * Returns a File::Stat object.
+ *
+ * See File.stat.
  */
 static VALUE
 path_stat(VALUE self)
@@ -492,7 +587,7 @@ path_stat(VALUE self)
 }
 
 /*
- * See <tt>File.lstat</tt>.
+ * See File.lstat.
  */
 static VALUE
 path_lstat(VALUE self)
@@ -504,7 +599,9 @@ path_lstat(VALUE self)
  * call-seq:
  *   pathname.make_symlink(old)
  *
- * See <tt>File.symlink</tt>.  Creates a symbolic link.
+ * Creates a symbolic link.
+ *
+ * See File.symlink.
  */
 static VALUE
 path_make_symlink(VALUE self, VALUE old)
@@ -513,7 +610,9 @@ path_make_symlink(VALUE self, VALUE old)
 }
 
 /*
- * See <tt>File.truncate</tt>.  Truncate the file to +length+ bytes.
+ * Truncates the file to +length+ bytes.
+ *
+ * See File.truncate.
  */
 static VALUE
 path_truncate(VALUE self, VALUE length)
@@ -522,7 +621,9 @@ path_truncate(VALUE self, VALUE length)
 }
 
 /*
- * See <tt>File.utime</tt>.  Update the access and modification times.
+ * Update the access and modification times of the file.
+ *
+ * See File.utime.
  */
 static VALUE
 path_utime(VALUE self, VALUE atime, VALUE mtime)
@@ -531,7 +632,9 @@ path_utime(VALUE self, VALUE atime, VALUE mtime)
 }
 
 /*
- * See <tt>File.basename</tt>.  Returns the last component of the path.
+ * Returns the last component of the path.
+ *
+ * See File.basename.
  */
 static VALUE
 path_basename(int argc, VALUE *argv, VALUE self)
@@ -546,7 +649,9 @@ path_basename(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * See <tt>File.dirname</tt>.  Returns all but the last component of the path.
+ * Returns all but the last component of the path.
+ *
+ * See File.dirname.
  */
 static VALUE
 path_dirname(VALUE self)
@@ -557,7 +662,9 @@ path_dirname(VALUE self)
 }
 
 /*
- * See <tt>File.extname</tt>.  Returns the file's extension.
+ * Returns the file's extension.
+ *
+ * See File.extname.
  */
 static VALUE
 path_extname(VALUE self)
@@ -567,7 +674,9 @@ path_extname(VALUE self)
 }
 
 /*
- * See <tt>File.expand_path</tt>.
+ * Returns the absolute path for the file.
+ *
+ * See File.expand_path.
  */
 static VALUE
 path_expand_path(int argc, VALUE *argv, VALUE self)
@@ -582,7 +691,9 @@ path_expand_path(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * See <tt>File.split</tt>.  Returns the #dirname and the #basename in an Array.
+ * Returns the #dirname and the #basename in an Array.
+ *
+ * See File.split.
  */
 static VALUE
 path_split(VALUE self)
@@ -599,7 +710,7 @@ path_split(VALUE self)
 }
 
 /*
- * See <tt>FileTest.blockdev?</tt>.
+ * See FileTest.blockdev?.
  */
 static VALUE
 path_blockdev_p(VALUE self)
@@ -608,7 +719,7 @@ path_blockdev_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.chardev?</tt>.
+ * See FileTest.chardev?.
  */
 static VALUE
 path_chardev_p(VALUE self)
@@ -617,7 +728,7 @@ path_chardev_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.executable?</tt>.
+ * See FileTest.executable?.
  */
 static VALUE
 path_executable_p(VALUE self)
@@ -626,7 +737,7 @@ path_executable_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.executable_real?</tt>.
+ * See FileTest.executable_real?.
  */
 static VALUE
 path_executable_real_p(VALUE self)
@@ -635,7 +746,7 @@ path_executable_real_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.exist?</tt>.
+ * See FileTest.exist?.
  */
 static VALUE
 path_exist_p(VALUE self)
@@ -644,7 +755,7 @@ path_exist_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.grpowned?</tt>.
+ * See FileTest.grpowned?.
  */
 static VALUE
 path_grpowned_p(VALUE self)
@@ -653,7 +764,7 @@ path_grpowned_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.directory?</tt>.
+ * See FileTest.directory?.
  */
 static VALUE
 path_directory_p(VALUE self)
@@ -662,7 +773,7 @@ path_directory_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.file?</tt>.
+ * See FileTest.file?.
  */
 static VALUE
 path_file_p(VALUE self)
@@ -671,7 +782,7 @@ path_file_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.pipe?</tt>.
+ * See FileTest.pipe?.
  */
 static VALUE
 path_pipe_p(VALUE self)
@@ -680,7 +791,7 @@ path_pipe_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.socket?</tt>.
+ * See FileTest.socket?.
  */
 static VALUE
 path_socket_p(VALUE self)
@@ -689,7 +800,7 @@ path_socket_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.owned?</tt>.
+ * See FileTest.owned?.
  */
 static VALUE
 path_owned_p(VALUE self)
@@ -698,7 +809,7 @@ path_owned_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.readable?</tt>.
+ * See FileTest.readable?.
  */
 static VALUE
 path_readable_p(VALUE self)
@@ -707,7 +818,7 @@ path_readable_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.world_readable?</tt>.
+ * See FileTest.world_readable?.
  */
 static VALUE
 path_world_readable_p(VALUE self)
@@ -716,7 +827,7 @@ path_world_readable_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.readable_real?</tt>.
+ * See FileTest.readable_real?.
  */
 static VALUE
 path_readable_real_p(VALUE self)
@@ -725,7 +836,7 @@ path_readable_real_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.setuid?</tt>.
+ * See FileTest.setuid?.
  */
 static VALUE
 path_setuid_p(VALUE self)
@@ -734,7 +845,7 @@ path_setuid_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.setgid?</tt>.
+ * See FileTest.setgid?.
  */
 static VALUE
 path_setgid_p(VALUE self)
@@ -743,7 +854,7 @@ path_setgid_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.size</tt>.
+ * See FileTest.size.
  */
 static VALUE
 path_size(VALUE self)
@@ -752,7 +863,7 @@ path_size(VALUE self)
 }
 
 /*
- * See <tt>FileTest.size?</tt>.
+ * See FileTest.size?.
  */
 static VALUE
 path_size_p(VALUE self)
@@ -761,7 +872,7 @@ path_size_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.sticky?</tt>.
+ * See FileTest.sticky?.
  */
 static VALUE
 path_sticky_p(VALUE self)
@@ -770,7 +881,7 @@ path_sticky_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.symlink?</tt>.
+ * See FileTest.symlink?.
  */
 static VALUE
 path_symlink_p(VALUE self)
@@ -779,7 +890,7 @@ path_symlink_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.writable?</tt>.
+ * See FileTest.writable?.
  */
 static VALUE
 path_writable_p(VALUE self)
@@ -788,7 +899,7 @@ path_writable_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.world_writable?</tt>.
+ * See FileTest.world_writable?.
  */
 static VALUE
 path_world_writable_p(VALUE self)
@@ -797,7 +908,7 @@ path_world_writable_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.writable_real?</tt>.
+ * See FileTest.writable_real?.
  */
 static VALUE
 path_writable_real_p(VALUE self)
@@ -806,7 +917,7 @@ path_writable_real_p(VALUE self)
 }
 
 /*
- * See <tt>FileTest.zero?</tt>.
+ * See FileTest.zero?.
  */
 static VALUE
 path_zero_p(VALUE self)
@@ -821,7 +932,12 @@ glob_i(VALUE elt, VALUE klass, int argc, VALUE *argv)
 }
 
 /*
- * See <tt>Dir.glob</tt>.  Returns or yields Pathname objects.
+ * Returns or yields Pathname objects.
+ *
+ *  Pathname.glob("config/*.rb")
+ *	#=> [#<Pathname:config/environment.rb>, #<Pathname:config/routes.rb>, ..]
+ *
+ * See Dir.glob.
  */
 static VALUE
 path_s_glob(int argc, VALUE *argv, VALUE klass)
@@ -848,7 +964,12 @@ path_s_glob(int argc, VALUE *argv, VALUE klass)
 }
 
 /*
- * See <tt>Dir.getwd</tt>.  Returns the current working directory as a Pathname.
+ * Returns the current working directory as a Pathname.
+ *
+ *	Pathname.getwd
+ *	    #=> #<Pathname:/home/zzak/projects/ruby>
+ *
+ * See Dir.getwd.
  */
 static VALUE
 path_s_getwd(VALUE klass)
@@ -862,13 +983,8 @@ path_s_getwd(VALUE klass)
  * Return the entries (files and subdirectories) in the directory, each as a
  * Pathname object.
  *
- * The result contains just a filename which has no directory.
- *
- * The result may contain the current directory #<Pathname:.> and the parent
- * directory #<Pathname:..>.
- *
- * If you don't want #<Pathname:.> and #<Pathname:..> and
- * want directory, consider Pathname#children.
+ * The results contains just the names in the directory, without any trailing
+ * slashes or recursive look-up.
  *
  *   pp Pathname.new('/usr/local').entries
  *   #=> [#<Pathname:share>,
@@ -883,6 +999,11 @@ path_s_getwd(VALUE klass)
  *   #    #<Pathname:sbin>,
  *   #    #<Pathname:src>]
  *
+ * The result may contain the current directory <code>#<Pathname:.></code> and
+ * the parent directory <code>#<Pathname:..></code>.
+ *
+ * If you don't want +.+ and +..+ and
+ * want directories, consider Pathname#children.
  */
 static VALUE
 path_entries(VALUE self)
@@ -902,7 +1023,9 @@ path_entries(VALUE self)
 }
 
 /*
- * See <tt>Dir.mkdir</tt>.  Create the referenced directory.
+ * Create the referenced directory.
+ *
+ * See Dir.mkdir.
  */
 static VALUE
 path_mkdir(int argc, VALUE *argv, VALUE self)
@@ -916,7 +1039,9 @@ path_mkdir(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- * See <tt>Dir.rmdir</tt>.  Remove the referenced directory.
+ * Remove the referenced directory.
+ *
+ * See Dir.rmdir.
  */
 static VALUE
 path_rmdir(VALUE self)
@@ -925,7 +1050,9 @@ path_rmdir(VALUE self)
 }
 
 /*
- * See <tt>Dir.open</tt>.
+ * Opens the referenced directory.
+ *
+ * See Dir.open.
  */
 static VALUE
 path_opendir(VALUE self)
@@ -943,10 +1070,8 @@ each_entry_i(VALUE elt, VALUE klass, int argc, VALUE *argv)
 }
 
 /*
- * Iterates over the entries (files and subdirectories) in the directory.  It
- * yields a Pathname object for each entry.
- *
- * This method has available since 1.8.1.
+ * Iterates over the entries (files and subdirectories) in the directory,
+ * yielding a Pathname object for each entry.
  */
 static VALUE
 path_each_entry(VALUE self)
@@ -970,8 +1095,8 @@ unlink_rescue(VALUE str, VALUE errinfo)
 }
 
 /*
- * Removes a file or directory, using <tt>File.unlink</tt> or
- * <tt>Dir.unlink</tt> as necessary.
+ * Removes a file or directory, using File.unlink if +self+ is a file, or
+ * Dir.unlink as necessary.
  */
 static VALUE
 path_unlink(VALUE self)
@@ -982,9 +1107,7 @@ path_unlink(VALUE self)
 }
 
 /*
- * create a pathname object.
- *
- * This method is available since 1.8.5.
+ * Creates a new Pathname object.
  */
 static VALUE
 path_f_pathname(VALUE self, VALUE str)
@@ -993,24 +1116,26 @@ path_f_pathname(VALUE self, VALUE str)
 }
 
 /*
- * == Pathname
  *
- * Pathname represents a pathname which locates a file in a filesystem.
- * The pathname depends on OS: Unix, Windows, etc.
- * Pathname library works with pathnames of local OS.
- * However non-Unix pathnames are supported experimentally.
+ * Pathname represents the name of a file or directory on the filesystem,
+ * but not the file itself.
+ *
+ * The pathname depends on the Operating System: Unix, Windows, etc.
+ * This library works with pathnames of local OS, however non-Unix pathnames
+ * are supported experimentally.
  *
- * It does not represent the file itself.
  * A Pathname can be relative or absolute.  It's not until you try to
  * reference the file that it even matters whether the file exists or not.
  *
  * Pathname is immutable.  It has no method for destructive update.
  *
- * The value of this class is to manipulate file path information in a neater
+ * The goal of this class is to manipulate file path information in a neater
  * way than standard Ruby provides.  The examples below demonstrate the
- * difference.  *All* functionality from File, FileTest, and some from Dir and
- * FileUtils is included, in an unsurprising way.  It is essentially a facade for
- * all of these, and more.
+ * difference.
+ *
+ * *All* functionality from File, FileTest, and some from Dir and FileUtils is
+ * included, in an unsurprising way.  It is essentially a facade for all of
+ * these, and more.
  *
  * == Examples
  *
@@ -1058,8 +1183,8 @@ path_f_pathname(VALUE self, VALUE str)
  * === Core methods
  *
  * These methods are effectively manipulating a String, because that's
- * all a path is.  Except for #mountpoint?, #children, #each_child,
- * #realdirpath and #realpath, they don't access the filesystem.
+ * all a path is.  None of these access the file system except for
+ * #mountpoint?, #children, #each_child, #realdirpath and #realpath.
  *
  * - +
  * - #join