From 49085c19f695901cdeac2b5cdae99e092ece38b0 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Mon, 8 Jun 2026 19:14:16 -0500
Subject: [PATCH] [DOC] Harmonize ftype methods (#17219)

---
 file.c              | 73 +++++++++++++++++++++++++++++++++++----------
 pathname_builtin.rb | 23 ++++++++++++--
 2 files changed, 78 insertions(+), 18 deletions(-)

diff --git a/file.c b/file.c
index fffd09c22e..661232f053 100644
--- a/file.c
+++ b/file.c
@@ -2443,17 +2443,35 @@ rb_file_ftype(mode_t mode)
 
 /*
  *  call-seq:
- *     File.ftype(file_name)   -> string
+ *    File.ftype(path) -> string
  *
- *  Identifies the type of the named file; the return string is one of
- *  ``<code>file</code>'', ``<code>directory</code>'',
- *  ``<code>characterSpecial</code>'', ``<code>blockSpecial</code>'',
- *  ``<code>fifo</code>'', ``<code>link</code>'',
- *  ``<code>socket</code>'', or ``<code>unknown</code>''.
+ *  Returns the string type of the object at +path+, one of:
  *
- *     File.ftype("testfile")            #=> "file"
- *     File.ftype("/dev/tty")            #=> "characterSpecial"
- *     File.ftype("/tmp/.X11-unix/X0")   #=> "socket"
+ *  - <tt>'file'</tt>.
+ *  - <tt>'directory'</tt>.
+ *  - <tt>'characterSpecial'</tt>.
+ *  - <tt>'blockSpecial'</tt>.
+ *  - <tt>'fifo'</tt>.
+ *  - <tt>'link'</tt>.
+ *  - <tt>'socket'</tt>.
+ *
+ *  Examples:
+ *
+ *    File.ftype('README.md')   # => "file"
+ *    File.ftype('lib')         # => "directory"
+ *    File.ftype("/dev/null")   # => "characterSpecial"
+ *    File.ftype("/dev/loop0")  # => "blockSpecial"
+ *
+ *    File.mkfifo('/tmp/pipe', 0666)
+ *    File.ftype('/tmp/pipe')   # => "fifo"
+ *
+ *    File.symlink('lib', 'lib_link')
+ *    File.ftype('lib_link')    # => "link"
+ *
+ *    UNIXServer.new('/tmp/socket')
+ *    File.ftype('/tmp/socket') # => "socket"
+ *
+ *  Returns <tt>'unknown'</tt> if the type cannot be determined.
  */
 
 static VALUE
@@ -6162,16 +6180,39 @@ rb_stat_init_copy(VALUE copy, VALUE orig)
 
 /*
  *  call-seq:
- *     stat.ftype   -> string
+ *     stat.ftype -> string
  *
- *  Identifies the type of <i>stat</i>. The return string is one of:
- *  ``<code>file</code>'', ``<code>directory</code>'',
- *  ``<code>characterSpecial</code>'', ``<code>blockSpecial</code>'',
- *  ``<code>fifo</code>'', ``<code>link</code>'',
- *  ``<code>socket</code>'', or ``<code>unknown</code>''.
+ *  Returns the string type of the object at +path+, one of:
  *
- *     File.stat("/dev/tty").ftype   #=> "characterSpecial"
+ *  - <tt>'file'</tt>.
+ *  - <tt>'directory'</tt>.
+ *  - <tt>'characterSpecial'</tt>.
+ *  - <tt>'blockSpecial'</tt>.
+ *  - <tt>'fifo'</tt>.
+ *  - <tt>'link'</tt>.
+ *  - <tt>'socket'</tt>.
  *
+ *  Examples:
+ *
+ *    File.stat('README.md').ftype  # => "file"
+ *    File.stat('lib').ftype        # => "directory"
+ *    File.stat('/dev/null').ftype  # => "characterSpecial"
+ *    File.stat('/dev/loop0').ftype # => "blockSpecial"
+ *
+ *    File.mkfifo('/tmp/pipe', 0666)
+ *    File.stat('/tmp/pipe').ftype  # => "fifo"
+ *
+ *    # Follows symbolic link.
+ *    File.symlink('lib', 'lib_link')
+ *    File.stat('lib_link').ftype   # => "directory"
+ *    # Does not follow symbolic link.
+ *    File.lstat('lib_link').ftype  # => "link"
+ *
+ *    require 'socket'
+ *    UNIXServer.new('/tmp/socket')
+ *    File.stat('/tmp/socket').ftype # => "socket"
+ *
+ *  Returns <tt>'unknown'</tt> if the type cannot be determined.
  */
 
 static VALUE
diff --git a/pathname_builtin.rb b/pathname_builtin.rb
index 11ade220f0..50cee40df4 100644
--- a/pathname_builtin.rb
+++ b/pathname_builtin.rb
@@ -1343,8 +1343,27 @@ class Pathname    # * File *
   # See <tt>File.fnmatch?</tt> (same as #fnmatch).
   def fnmatch?(pattern, ...) File.fnmatch?(pattern, @path, ...) end
 
-  # See <tt>File.ftype</tt>.  Returns "type" of file ("file", "directory",
-  # etc).
+  #  call-seq:
+  #    pathname.ftype -> string
+  #
+  #  Returns the string type of the object at the path in +self+:
+  #
+  #    Pathname('README.md').ftype   # => "file"
+  #    Pathname('lib').ftype         # => "directory"
+  #    Pathname('/dev/null').ftype   # => "characterSpecial"
+  #    Pathname('/dev/loop0').ftype  # => "blockSpecial"
+  #
+  #    File.mkfifo('/tmp/pipe', 0666)
+  #    Pathname('/tmp/pipe').ftype   # => "fifo"
+  #
+  #    File.symlink('lib', 'lib_link')
+  #    Pathname('lib_link').ftype    # => "link"
+  #
+  #    require 'socket'
+  #    UNIXServer.new('/tmp/socket')
+  #    Pathname('/tmp/socket').ftype # => "socket"
+  #
+  #  Returns <tt>'unknown'</tt> if the type cannot be determined.
   def ftype() File.ftype(@path) end
 
   # See <tt>File.link</tt>.  Creates a hard link.