diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 6eb95db3d..126fb0fde 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -390,14 +390,18 @@ Return an integer representing the current position of
 
 @findex truncate
 @findex ftruncate
-@deffn {Scheme Procedure} truncate-file object [length]
-@deffnx {C Function} scm_truncate_file (object, length)
-Truncates the object referred to by @var{object} to at most
-@var{length} bytes.  @var{object} can be a string containing a
-file name or an integer file descriptor or a port.
-@var{length} may be omitted if @var{object} is not a file name,
-in which case the truncation occurs at the current port
-position.  The return value is unspecified.
+@deffn {Scheme Procedure} truncate-file file [length]
+@deffnx {C Function} scm_truncate_file (file, length)
+Truncate @var{file} to @var{length} bytes.  @var{file} can be a
+filename string, a port object, or an integer file descriptor.  The
+return value is unspecified.
+
+For a port or file descriptor @var{length} can be omitted, in which
+case the file is truncated at the current position (per @code{ftell}
+above).
+
+On most systems a file can be extended by giving a length greater than
+the current size, but this is not mandatory in the POSIX standard.
 @end deffn
 
 @node Line/Delimited