diff --git a/lib/std/Io/File.zig b/lib/std/Io/File.zig
index 3aa68820e893409e7e47fb64a6bf246024a2db66..9dee99c86241d1490658e72d621816c4dedff197 100644
--- a/lib/std/Io/File.zig
+++ b/lib/std/Io/File.zig
@@ -268,6 +268,12 @@ pub const SetLengthError = error{
 /// Truncates or expands the file, populating any new data with zeroes.
 ///
 /// The file offset after this call is left unchanged.
+///
+/// This function operates on an open file handle. There is not an equivalent
+/// function in `Dir` which operates on paths because generally, such
+/// functionality will introduce Time-Of-Check, Time-Of-Use (TOCTOU) bugs. In
+/// the rare case when those semantics are actually needed, it is reasonable to
+/// open the file with the truncate flag.
 pub fn setLength(file: File, io: Io, new_length: u64) SetLengthError!void {
     return io.vtable.fileSetLength(io.userdata, file, new_length);
 }