diff --git a/file.c b/file.c
index 7bdaebc311a026..412bc2e874368d 100644
--- a/file.c
+++ b/file.c
@@ -1156,12 +1156,29 @@ rb_stat_atime(VALUE self)
}
/*
+ * :markup: markdown
+
* call-seq:
- * stat.mtime -> time
+ * mtime -> time
*
- * Returns the modification time of stat.
+ * Returns a new Time object containing the modification time
+ * of the object represented by `self`
+ * at the time `self` was created;
+ * see [Snapshot](rdoc-ref:File::Stat@Snapshot):
*
- * File.stat("testfile").mtime #=> Wed Apr 09 08:53:14 CDT 2003
+ * ```ruby
+ * path = 't.tmp'
+ * file = File.new(path, 'w+')
+ * stat = File.stat(path)
+ * stat.mtime # => 2026-09-19 08:49:08.846933858 -0500
+ * file.write('foo')
+ * file.flush
+ * File.mtime(path) # => 2026-09-19 08:50:14.381365572 -0500
+ * stat.mtime # => 2026-09-19 08:49:08.846933858 -0500
+ * stat = File.stat(path)
+ * stat.mtime # => 2026-09-19 08:50:14.381365572 -0500
+ * File.unlink(path) # Clean up.
+ * ```
*
*/
@@ -2738,14 +2755,34 @@ rb_file_atime(VALUE obj)
}
/*
- * call-seq:
- * File.mtime(file_name) -> time
+ * :markup: markdown
*
- * Returns the modification time for the named file as a Time object.
+ * call-seq:
+ * File.mtime(object) -> time
*
- * _file_name_ can be an IO object.
+ * Returns a new Time object containing the modification time for the given object,
+ * which may be a string path or an IO object;
+ * see [Modification Time](rdoc-ref:file/timestamps.md@Modification+Time):
*
- * File.mtime("testfile") #=> Tue Apr 08 12:58:04 CDT 2003
+ * ```ruby
+ * # Create directory; directory mtime established.
+ * dirpath = 'doc/foo' # => "doc/foo"
+ * Dir.mkdir(dirpath)
+ * File.mtime(dirpath) # => 2026-09-19 09:01:30.045928322 -0500
+ * # Create file therein; file mtime established, directory mtime updated.
+ * filepath = File.join(dirpath, 't.tmp') # => "doc/foo/t.tmp"
+ * File.write(filepath, 'foo')
+ * File.mtime(filepath) # => 2026-09-19 09:02:32.860803131 -0500
+ * File.mtime(dirpath) # => 2026-09-19 09:02:32.860803131 -0500
+ * # Modify file; file mtime updated, directory mtime unchanged.
+ * File.write(filepath, 'bar')
+ * File.mtime(filepath) # => 2026-09-19 09:03:29.875611413 -0500
+ * File.mtime(dirpath) # => 2026-09-19 09:02:32.860803131 -0500
+ * FileUtils.rm_rf(dirpath) # Clean up.
+ * File.mtime($stdout) # => 2026-09-19 09:27:52 -0500
+ * $stdout.flush
+ * File.mtime($stdout) # => 2026-09-19 09:28:08 -0500
+ * ```
*
*/
@@ -2763,12 +2800,23 @@ rb_file_s_mtime(VALUE klass, VALUE fname)
}
/*
+ * :markup: markdown
+ *
* call-seq:
- * file.mtime -> time
+ * mtime -> time
*
- * Returns the modification time for file.
+ * Returns a new Time object containing the modification time for `self`;
+ * see [Modification Time](rdoc-ref:file/timestamps.md@Modification+Time):
*
- * File.new("testfile").mtime #=> Wed Apr 09 08:53:14 CDT 2003
+ * ```ruby
+ * path = 't.tmp'
+ * file = File.new(path, 'w+')
+ * file.mtime # => 2026-09-19 08:41:29.357110007 -0500
+ * file.write('foo')
+ * file.flush
+ * file.mtime # => 2026-09-19 08:41:46.321965574 -0500
+ * File.unlink(path)
+ * ```
*
*/
@@ -7346,13 +7394,24 @@ nogvl_mkfifo(void *ptr)
}
/*
+ * :markup: markdown
+ *
* call-seq:
- * File.mkfifo(file_name, mode=0666) => 0
+ * File.mkfifo(path, mode = 0666) -> 0
+ *
+ * Creates a FIFO special file at the given `path`,
+ * with the permissions given by `mode`;
+ * see [Filesystem Modes](rdoc-ref:file/filesystem_modes.md):
+ *
+ * ```ruby
+ * path = '/tmp/pipe'
+ * File.mkfifo(path)
+ * File.pipe?(path) # => true
+ * File.ftype(path) # => "fifo"
+ * File.unlink(path)
+ * ```
*
- * Creates a FIFO special file with name _file_name_. _mode_
- * specifies the FIFO's permissions. It is modified by the process's
- * umask in the usual way: the permissions of the created file are
- * (mode & ~umask).
+ * Not implemented on Windows.
*/
static VALUE