rbs 3.10.0 → 4.0.0.dev.1

data/{core → stdlib/pathname/0}/pathname.rbs

@@ -1,18 +1,4 @@
-# <!-- rdoc-file=lib/pathname.rb -->
-# # pathname.rb
-#
-# Object-Oriented Pathname Class
-#
-# Author
-# :   Tanaka Akira <akr@m17n.org>
-#
-# Documentation
-# :   Author and Gavin Sinclair
-#
-#
-# For documentation, see class Pathname.
-#
-# <!-- rdoc-file=pathname_builtin.rb -->
+# <!-- rdoc-file=ext/pathname/pathname.c -->
 # Pathname represents the name of a file or directory on the filesystem, but not
 # the file itself.
 #
@@ -127,13 +113,6 @@
 # ### File property and manipulation methods
 #
 # These methods are a facade for File:
-# *   #each_line(*args, &block)
-# *   #read(*args)
-# *   #binread(*args)
-# *   #readlines(*args)
-# *   #sysopen(*args)
-# *   #write(*args)
-# *   #binwrite(*args)
 # *   #atime
 # *   #birthtime
 # *   #ctime
@@ -172,6 +151,17 @@
 # *   #mkdir(*args)
 # *   #opendir(*args)
 #
+# ### IO
+#
+# These methods are a facade for IO:
+# *   #each_line(*args, &block)
+# *   #read(*args)
+# *   #binread(*args)
+# *   #readlines(*args)
+# *   #sysopen(*args)
+# *   #write(*args)
+# *   #binwrite(*args)
+#
 # ### Utilities
 #
 # These methods are a mixture of Find, FileUtils, and others:
@@ -190,31 +180,47 @@
 #
 class Pathname
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - getwd()
   # -->
-  # See `Dir.getwd`.  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.
   #
   def self.getwd: () -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - glob(*args, **kwargs) { |pathname| ... }
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - glob(p1, p2 = v2, p3 = v3)
   # -->
-  # See `Dir.glob`.  Returns or yields Pathname objects.
+  # Returns or yields Pathname objects.
+  #
+  #     Pathname.glob("lib/i*.rb")
+  #         #=> [#<Pathname:lib/ipaddr.rb>, #<Pathname:lib/irb.rb>]
+  #
+  # See Dir.glob.
   #
   def self.glob: (String | Array[String] pattern, ?Integer flags) -> Array[Pathname]
                | (String | Array[String] pattern, ?Integer flags) { (Pathname) -> untyped } -> nil
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - pwd()
   # -->
+  # Returns the current working directory as a Pathname.
+  #
+  #     Pathname.getwd
+  #         #=> #<Pathname:/home/zzak/projects/ruby>
+  #
+  # See Dir.getwd.
   #
   def self.pwd: () -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - +(other)
   # -->
   # Appends a pathname fragment to `self` to produce a new Pathname object. Since
@@ -234,14 +240,14 @@ class Pathname
   def +: (Pathname | String | _ToStr other) -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - /(other)
   # -->
   #
   alias / +
 
   # <!--
-  #   rdoc-file=pathname.c
+  #   rdoc-file=ext/pathname/pathname.c
   #   - <=>(p1)
   # -->
   # Provides a case-sensitive comparison operator for pathnames.
@@ -261,8 +267,8 @@ class Pathname
          | (untyped other) -> nil
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - ==(other)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - ==(p1)
   # -->
   # Compare this pathname with `other`.  The comparison is string-based. Be aware
   # that two different paths (`foo.txt` and `./foo.txt`) can refer to the same
@@ -270,15 +276,15 @@ class Pathname
   #
   def ==: (untyped) -> bool
 
-  # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - ===(other)
-  # -->
+  # <!-- rdoc-file=ext/pathname/pathname.c -->
+  # Compare this pathname with `other`.  The comparison is string-based. Be aware
+  # that two different paths (`foo.txt` and `./foo.txt`) can refer to the same
+  # file.
   #
   def ===: (untyped) -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - absolute?()
   # -->
   # Predicate method for testing whether a path is absolute.
@@ -296,7 +302,7 @@ class Pathname
   def absolute?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - ascend() { |self| ... }
   # -->
   # Iterates over and yields a new Pathname object for each element in the given
@@ -328,33 +334,39 @@ class Pathname
             | () -> Enumerator[Pathname, nil]
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - atime()
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.atime     -> time
   # -->
-  # See `File.atime`.  Returns last access time.
+  # Returns the last access time for the file.
+  #
+  # See File.atime.
   #
   def atime: () -> Time
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - basename(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - basename(p1 = v1)
   # -->
-  # See `File.basename`.  Returns the last component of the path.
+  # Returns the last component of the path.
+  #
+  # See File.basename.
   #
   def basename: (?String | _ToStr suffix) -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - binread(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.binread([length [, offset]]) -> string
   # -->
-  # See `File.binread`.  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 File.binread.
   #
   def binread: (?Integer length, ?Integer offset) -> String
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - binwrite(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.binwrite(string, [offset] )   => fixnum
+  #   - pathname.binwrite(string, [offset], open_args )   => fixnum
   # -->
   # Writes `contents` to the file, opening it in binary mode.
   #
@@ -363,8 +375,8 @@ class Pathname
   def binwrite: (String, ?Integer offset, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?invalid: :replace ?, ?undef: :replace ?, ?replace: String, ?fallback: Hash[String, String] | Proc | Method, ?xml: :text | :attr, ?universal_newline: true, ?cr_newline: true, ?crlf_newline: true) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - birthtime()
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.birthtime -> time
   # -->
   # Returns the birth time for the file. If the platform doesn't have birthtime,
   # raises NotImplementedError.
@@ -374,23 +386,23 @@ class Pathname
   def birthtime: () -> Time
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - blockdev?()
   # -->
-  # See `FileTest.blockdev?`.
+  # See FileTest.blockdev?.
   #
   def blockdev?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - chardev?()
   # -->
-  # See `FileTest.chardev?`.
+  # See FileTest.chardev?.
   #
   def chardev?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - children(with_directory=true)
   # -->
   # Returns the children of the directory (files and subdirectories, not
@@ -415,23 +427,27 @@ class Pathname
   def children: (?boolish with_directory) -> Array[Pathname]
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - chmod(mode)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.chmod(mode_int)   -> integer
   # -->
-  # See `File.chmod`.  Changes permissions.
+  # Changes file permissions.
+  #
+  # See File.chmod.
   #
   def chmod: (Integer mode_int) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - chown(owner, group)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.chown(owner_int, group_int)       -> integer
   # -->
-  # See `File.chown`.  Change owner and group of file.
+  # Change owner and group of the file.
+  #
+  # See File.chown.
   #
   def chown: (Integer owner, Integer group) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - cleanpath(consider_symlink=false)
   # -->
   # Returns clean pathname of `self` with consecutive slashes and useless dots
@@ -447,22 +463,24 @@ class Pathname
   def cleanpath: (?boolish consider_symlink) -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - ctime()
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.ctime     -> time
   # -->
-  # See `File.ctime`.  Returns last (directory entry, not file) change time.
+  # Returns the last change time, using directory information, not the file
+  # itself.
+  #
+  # See File.ctime.
   #
   def ctime: () -> Time
 
-  # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - delete()
-  # -->
+  # <!-- rdoc-file=ext/pathname/pathname.c -->
+  # Removes a file or directory, using File.unlink if `self` is a file, or
+  # Dir.unlink as necessary.
   #
   def delete: () -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - descend() { |v| ... }
   # -->
   # Iterates over and yields a new Pathname object for each element in the given
@@ -494,23 +512,25 @@ class Pathname
              | () -> Enumerator[Pathname, nil]
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - directory?()
   # -->
-  # See `FileTest.directory?`.
+  # See FileTest.directory?.
   #
   def directory?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - dirname()
   # -->
-  # See `File.dirname`.  Returns all but the last component of the path.
+  # Returns all but the last component of the path.
+  #
+  # See File.dirname.
   #
   def dirname: () -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - each_child(with_directory=true, &b)
   # -->
   # Iterates over the children of the directory (files and subdirectories, not
@@ -553,18 +573,16 @@ class Pathname
                 | (?boolish with_directory) -> Enumerator[Pathname, Array[Pathname]]
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - each_entry() { |pathname| ... }
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - each_entry()
   # -->
-  # Iterates over the entries (files and subdirectories) in the directory.  It
-  # yields a Pathname object for each entry.
-  #
-  # This method has existed since 1.8.1.
+  # Iterates over the entries (files and subdirectories) in the directory,
+  # yielding a Pathname object for each entry.
   #
   def each_entry: () { (Pathname) -> untyped } -> nil
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - each_filename() { |filename| ... }
   # -->
   # Iterates over each component of the path.
@@ -583,13 +601,14 @@ class Pathname
                    | () -> Enumerator[String, nil]
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - each_line(...) { |line| ... }
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.each_line {|line| ... }
+  #   - pathname.each_line(sep=$/ [, open_args]) {|line| block }     -> nil
+  #   - pathname.each_line(limit [, open_args]) {|line| block }      -> nil
+  #   - 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 has existed since 1.8.1.
+  # Iterates over each line in the file and yields a String object for each.
   #
   def each_line: (?String sep, ?Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) { (String) -> untyped } -> nil
                | (Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) { (String) -> untyped } -> nil
@@ -597,7 +616,7 @@ class Pathname
                | (Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) -> Enumerator[String, nil]
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - empty?()
   # -->
   # Tests the file is empty.
@@ -607,78 +626,102 @@ class Pathname
   def empty?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - entries()
   # -->
   # Return the entries (files and subdirectories) in the directory, each as a
   # Pathname object.
   #
+  # 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>,
+  #     #    #<Pathname:lib>,
+  #     #    #<Pathname:..>,
+  #     #    #<Pathname:include>,
+  #     #    #<Pathname:etc>,
+  #     #    #<Pathname:bin>,
+  #     #    #<Pathname:man>,
+  #     #    #<Pathname:games>,
+  #     #    #<Pathname:.>,
+  #     #    #<Pathname:sbin>,
+  #     #    #<Pathname:src>]
+  #
+  # The result may contain the current directory `#<Pathname:.>` and the parent
+  # directory `#<Pathname:..>`.
+  #
+  # If you don't want `.` and `..` and want directories, consider
+  # Pathname#children.
+  #
   def entries: () -> Array[Pathname]
 
-  # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - eql?(other)
-  # -->
+  # <!-- rdoc-file=ext/pathname/pathname.c -->
+  # Compare this pathname with `other`.  The comparison is string-based. Be aware
+  # that two different paths (`foo.txt` and `./foo.txt`) can refer to the same
+  # file.
   #
   def eql?: (untyped) -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - executable?()
   # -->
-  # See `FileTest.executable?`.
+  # See FileTest.executable?.
   #
   def executable?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - executable_real?()
   # -->
-  # See `FileTest.executable_real?`.
+  # See FileTest.executable_real?.
   #
   def executable_real?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - exist?()
   # -->
-  # See `FileTest.exist?`.
+  # See FileTest.exist?.
   #
   def exist?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - expand_path(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - expand_path(p1 = v1)
   # -->
-  # See `File.expand_path`.
+  # Returns the absolute path for the file.
+  #
+  # See File.expand_path.
   #
   def expand_path: (?String dir) -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - extname()
   # -->
-  # See `File.extname`.  Returns the file's extension.
+  # Returns the file's extension.
+  #
+  # See File.extname.
   #
   def extname: () -> String
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - file?()
   # -->
-  # See `FileTest.file?`.
+  # See FileTest.file?.
   #
   def file?: () -> bool
 
   # <!--
-  #   rdoc-file=lib/pathname.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - find(ignore_error: true) { |pathname| ... }
   # -->
   # Iterates over the directory tree in a depth first manner, yielding a Pathname
   # for each file under "this" directory.
   #
-  # Note that you need to require 'pathname' to use this method.
-  #
   # Returns an Enumerator if no block is given.
   #
   # Since it is implemented by the standard library module Find, Find.prune can be
@@ -693,40 +736,46 @@ class Pathname
           | (?ignore_error: boolish) -> Enumerator[Pathname, nil]
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - fnmatch(pattern, ...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.fnmatch(pattern, [flags])        -> true or false
+  #   - pathname.fnmatch?(pattern, [flags])       -> true or false
   # -->
-  # See `File.fnmatch`.  Return `true` if the receiver matches the given pattern.
+  # Return `true` if the receiver matches the given pattern.
+  #
+  # See File.fnmatch.
   #
   def fnmatch: (String pattern, ?Integer flags) -> bool
 
-  # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - fnmatch?(pattern, ...)
-  # -->
-  # See `File.fnmatch?` (same as #fnmatch).
+  # <!-- rdoc-file=ext/pathname/pathname.c -->
+  # Return `true` if the receiver matches the given pattern.
+  #
+  # See File.fnmatch.
   #
   alias fnmatch? fnmatch
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - freeze()
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.freeze -> obj
   # -->
-  # Freze self.
+  # Freezes this Pathname.
+  #
+  # See Object.freeze.
   #
   def freeze: () -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - ftype()
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.ftype     -> string
   # -->
-  # See `File.ftype`.  Returns "type" of file ("file", "directory", etc).
+  # Returns "type" of file ("file", "directory", etc).
+  #
+  # See File.ftype.
   #
   def ftype: () -> String
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - glob(*args, **kwargs) { |pathname| ... }
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - glob(p1, p2 = v2)
   # -->
   # Returns or yields Pathname objects.
   #
@@ -739,10 +788,10 @@ class Pathname
           | (String | Array[String] pattern, ?Integer flags) { (Pathname) -> untyped } -> nil
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - grpowned?()
   # -->
-  # See `FileTest.grpowned?`.
+  # See FileTest.grpowned?.
   #
   def grpowned?: () -> bool
 
@@ -751,7 +800,7 @@ class Pathname
   def inspect: () -> String
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - join(*args)
   # -->
   # Joins the given pathnames onto `self` to create a new Pathname object. This is
@@ -768,32 +817,36 @@ class Pathname
   def join: (*String | _ToStr | Pathname args) -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - lchmod(mode)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.lchmod(mode_int)  -> integer
   # -->
-  # See `File.lchmod`.
+  # Same as Pathname.chmod, but does not follow symbolic links.
+  #
+  # See File.lchmod.
   #
   def lchmod: (Integer mode) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - lchown(owner, group)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.lchown(owner_int, group_int)      -> integer
   # -->
-  # See `File.lchown`.
+  # Same as Pathname.chown, but does not follow symbolic links.
+  #
+  # See File.lchown.
   #
   def lchown: (Integer owner, Integer group) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - lstat()
   # -->
-  # See `File.lstat`.
+  # See File.lstat.
   #
   def lstat: () -> ::File::Stat
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - lutime(atime, mtime)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - lutime(p1, p2)
   # -->
   # Update the access and modification times of the file.
   #
@@ -804,31 +857,37 @@ class Pathname
   def lutime: (Time | Numeric atime, Time | Numeric mtime) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - make_link(old)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.make_link(old)
   # -->
-  # See `File.link`.  Creates a hard link.
+  # Creates a hard link at *pathname*.
+  #
+  # See File.link.
   #
   def make_link: (String | Pathname | _ToStr old) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - make_symlink(old)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.make_symlink(old)
   # -->
-  # See `File.symlink`.  Creates a symbolic link.
+  # Creates a symbolic link.
+  #
+  # See File.symlink.
   #
   def make_symlink: (String | Pathname | _ToStr old) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - mkdir(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - mkdir(p1 = v1)
   # -->
-  # See `Dir.mkdir`.  Create the referenced directory.
+  # Create the referenced directory.
+  #
+  # See Dir.mkdir.
   #
   def mkdir: (?Integer perm) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - mkpath(mode: nil)
   # -->
   # Creates a full path, including any intermediate directories that don't yet
@@ -839,7 +898,7 @@ class Pathname
   def mkpath: () -> self
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - mountpoint?()
   # -->
   # Returns `true` if `self` points to a mountpoint.
@@ -847,41 +906,51 @@ class Pathname
   def mountpoint?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - mtime()
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.mtime     -> time
   # -->
-  # See `File.mtime`.  Returns last modification time.
+  # Returns the last modified time of the file.
+  #
+  # See File.mtime.
   #
   def mtime: () -> Time
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - open(...) { |file| ... }
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.open()
+  #   - pathname.open(mode="r" [, opt])                        -> file
+  #   - pathname.open([mode [, perm]] [, opt])                 -> file
+  #   - pathname.open(mode="r" [, opt]) {|file| block }        -> obj
+  #   - pathname.open([mode [, perm]] [, opt]) {|file| block } -> obj
   # -->
-  # See `File.open`.  Opens the file for reading or writing.
+  # Opens the file for reading or writing.
+  #
+  # See File.open.
   #
   def open: (?string | int mode, ?int perm) -> File
           | [T] (?string | int mode, ?int perm) { (File) -> T } -> T
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - opendir() { |dir| ... }
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - opendir()
   # -->
-  # See `Dir.open`.
+  # Opens the referenced directory.
+  #
+  # See Dir.open.
   #
   def opendir: () -> Dir
              | [U] () { (Dir) -> U } -> U
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - owned?()
   # -->
-  # See `FileTest.owned?`.
+  # See FileTest.owned?.
   #
   def owned?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - parent()
   # -->
   # Returns the parent directory.
@@ -891,58 +960,66 @@ class Pathname
   def parent: () -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - pipe?()
   # -->
-  # See `FileTest.pipe?`.
+  # See FileTest.pipe?.
   #
   def pipe?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - read(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.read([length [, offset]]) -> string
+  #   - pathname.read([length [, offset]], open_args) -> string
   # -->
-  # See `File.read`.  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 File.read.
   #
   def read: (?Integer length, ?Integer offset, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish) -> String
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - readable?()
   # -->
-  # See `FileTest.readable?`.
+  # See FileTest.readable?.
   #
   def readable?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - readable_real?()
   # -->
-  # See `FileTest.readable_real?`.
+  # See FileTest.readable_real?.
   #
   def readable_real?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - readlines(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.readlines(sep=$/ [, open_args])     -> array
+  #   - pathname.readlines(limit [, open_args])      -> array
+  #   - pathname.readlines(sep, limit [, open_args]) -> array
   # -->
-  # See `File.readlines`.  Returns all the lines from the file.
+  # Returns all the lines from the file.
+  #
+  # See File.readlines.
   #
   def readlines: (?String sep, ?Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) -> Array[String]
                | (Integer limit, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?chomp: boolish) -> Array[String]
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - readlink()
   # -->
-  # See `File.readlink`.  Read symbolic link.
+  # Read symbolic link.
+  #
+  # See File.readlink.
   #
   def readlink: () -> untyped
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - realdirpath(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - realdirpath(p1 = v1)
   # -->
   # Returns the real (absolute) pathname of `self` in the actual filesystem.
   #
@@ -953,8 +1030,8 @@ class Pathname
   def realdirpath: (?string | Pathname base_dir) -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - realpath(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - realpath(p1 = v1)
   # -->
   # Returns the real (absolute) pathname for `self` in the actual filesystem.
   #
@@ -965,7 +1042,7 @@ class Pathname
   def realpath: (?string | Pathname base_dir) -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - relative?()
   # -->
   # The opposite of Pathname#absolute?
@@ -983,7 +1060,7 @@ class Pathname
   def relative?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - relative_path_from(base_directory)
   # -->
   # Returns a relative path from the given `base_directory` to the receiver.
@@ -1002,35 +1079,37 @@ class Pathname
   def relative_path_from: (Pathname | string base_directory) -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - rename(to)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - rename(p1)
   # -->
-  # See `File.rename`.  Rename the file.
+  # Rename the file.
+  #
+  # See File.rename.
   #
   def rename: (Pathname | string new_name) -> 0
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - rmdir()
   # -->
-  # See `Dir.rmdir`.  Remove the referenced directory.
+  # Remove the referenced directory.
+  #
+  # See Dir.rmdir.
   #
   def rmdir: () -> 0
 
   # <!--
-  #   rdoc-file=lib/pathname.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - rmtree(noop: nil, verbose: nil, secure: nil)
   # -->
   # 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: () -> self
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/lib/pathname.rb
   #   - root?()
   # -->
   # Predicate method for root directories.  Returns `true` if the pathname
@@ -1042,71 +1121,75 @@ class Pathname
   def root?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - setgid?()
   # -->
-  # See `FileTest.setgid?`.
+  # See FileTest.setgid?.
   #
   def setgid?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - setuid?()
   # -->
-  # See `FileTest.setuid?`.
+  # See FileTest.setuid?.
   #
   def setuid?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - size()
   # -->
-  # See `FileTest.size`.
+  # See FileTest.size.
   #
   def size: () -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - size?()
   # -->
-  # See `FileTest.size?`.
+  # See FileTest.size?.
   #
   def size?: () -> Integer?
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - socket?()
   # -->
-  # See `FileTest.socket?`.
+  # See FileTest.socket?.
   #
   def socket?: () -> untyped
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - split()
   # -->
-  # See `File.split`.  Returns the #dirname and the #basename in an Array.
+  # Returns the #dirname and the #basename in an Array.
+  #
+  # See File.split.
   #
   def split: () -> [ Pathname, Pathname ]
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - stat()
   # -->
-  # See `File.stat`.  Returns a `File::Stat` object.
+  # Returns a File::Stat object.
+  #
+  # See File.stat.
   #
   def stat: () -> File::Stat
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - sticky?()
   # -->
-  # See `FileTest.sticky?`.
+  # See FileTest.sticky?.
   #
   def sticky?: () -> untyped
 
   # <!--
-  #   rdoc-file=pathname.c
+  #   rdoc-file=ext/pathname/pathname.c
   #   - sub(*args)
   # -->
   # Return a pathname which is substituted by String#sub.
@@ -1119,8 +1202,8 @@ class Pathname
          | (Regexp | string pattern) { (String match) -> string } -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - sub_ext(repl)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - sub_ext(p1)
   # -->
   # Return a pathname with `repl` added as a suffix to the basename.
   #
@@ -1132,18 +1215,18 @@ class Pathname
   def sub_ext: (string replacement) -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - symlink?()
   # -->
-  # See `FileTest.symlink?`.
+  # See FileTest.symlink?.
   #
   def symlink?: () -> untyped
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - sysopen(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.sysopen([mode, [perm]])  -> fixnum
   # -->
-  # See `File.sysopen`.
+  # See IO.sysopen.
   #
   def sysopen: (?String mode, ?Integer perm) -> Integer
 
@@ -1155,32 +1238,40 @@ class Pathname
   #
   def taint: () -> Pathname
 
-  # <!-- rdoc-file=pathname_builtin.rb -->
+  # <!-- rdoc-file=ext/pathname/pathname.c -->
+  # Return the path as a String.
+  #
   # to_path is implemented so Pathname objects are usable with File.open, etc.
   #
   def to_path: () -> String
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - to_s()
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.to_s             -> string
+  #   - pathname.to_path          -> string
   # -->
   # Return the path as a String.
   #
+  # to_path is implemented so Pathname objects are usable with File.open, etc.
+  #
   alias to_s to_path
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - truncate(length)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - truncate(p1)
   # -->
-  # See `File.truncate`.  Truncate the file to `length` bytes.
+  # Truncates the file to `length` bytes.
+  #
+  # See File.truncate.
   #
   def truncate: (Integer length) -> 0
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - unlink()
   # -->
-  # Removes a file or directory, using `File.unlink` or `Dir.unlink` as necessary.
+  # Removes a file or directory, using File.unlink if `self` is a file, or
+  # Dir.unlink as necessary.
   #
   def unlink: () -> Integer
 
@@ -1193,58 +1284,63 @@ class Pathname
   def untaint: () -> Pathname
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - utime(atime, mtime)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - utime(p1, p2)
   # -->
-  # See `File.utime`.  Update the access and modification times.
+  # Update the access and modification times of the file.
+  #
+  # See File.utime.
   #
   def utime: (Integer | Time atime, Integer | Time mtime) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - world_readable?()
   # -->
-  # See `FileTest.world_readable?`.
+  # See FileTest.world_readable?.
   #
   def world_readable?: () -> (Integer | nil)
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - world_writable?()
   # -->
-  # See `FileTest.world_writable?`.
+  # See FileTest.world_writable?.
   #
   def world_writable?: () -> (Integer | nil)
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - writable?()
   # -->
-  # See `FileTest.writable?`.
+  # See FileTest.writable?.
   #
   def writable?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - writable_real?()
   # -->
-  # See `FileTest.writable_real?`.
+  # See FileTest.writable_real?.
   #
   def writable_real?: () -> bool
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - write(...)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - pathname.write(string, [offset] )   => fixnum
+  #   - pathname.write(string, [offset], open_args )   => fixnum
   # -->
-  # Writes `contents` to the file. See `File.write`.
+  # Writes `contents` to the file.
+  #
+  # See File.write.
   #
   def write: (String content, ?Integer offset, ?mode: Integer | String, ?flags: Integer, ?external_encoding: encoding, ?internal_encoding: encoding, ?encoding: encoding, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish) -> Integer
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
+  #   rdoc-file=ext/pathname/pathname.c
   #   - zero?()
   # -->
-  # See `FileTest.zero?`.
+  # See FileTest.zero?.
   #
   def zero?: () -> bool
 
@@ -1263,11 +1359,11 @@ class Pathname
   def has_trailing_separator?: (untyped path) -> untyped
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - new(path)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - new(p1)
   # -->
   # Create a Pathname object from the given String (or String-like object). If
-  # `path` contains a NUL character (`\0`), an ArgumentError is raised.
+  # `path` contains a NULL character (`\0`), an ArgumentError is raised.
   #
   def initialize: (string | Pathname) -> void
 
@@ -1279,14 +1375,8 @@ class Pathname
 
   SAME_PATHS: Proc
 
-  # <!-- rdoc-file=pathname_builtin.rb -->
-  # Separator list string.
-  #
   SEPARATOR_LIST: String
 
-  # <!-- rdoc-file=pathname_builtin.rb -->
-  # Regexp that matches a separator.
-  #
   SEPARATOR_PAT: Regexp
 
   TO_PATH: Symbol
@@ -1297,10 +1387,20 @@ module Kernel
   private
 
   # <!--
-  #   rdoc-file=pathname_builtin.rb
-  #   - Pathname(path)
+  #   rdoc-file=ext/pathname/pathname.c
+  #   - Pathname(path)  -> pathname
   # -->
-  # Creates a Pathname object.
+  # Creates a new Pathname object from the given string, `path`, and returns
+  # pathname object.
+  #
+  # In order to use this constructor, you must first require the Pathname standard
+  # library extension.
+  #
+  #     require 'pathname'
+  #     Pathname("/home/zzak")
+  #     #=> #<Pathname:/home/zzak>
+  #
+  # See also Pathname::new for more information.
   #
   def self?.Pathname: (string | Pathname) -> Pathname
 end