; Fix documentation of 'file-parent-directory'

* doc/lispref/files.texi (Directory Names):
* lisp/files.el (file-parent-directory): Improve wording of the
documentation of 'file-parent-directory'.  (Bug#56355)

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index ee4e1ec4d96277a8f0acb7ae163cbf8a0cfecc56..986fb22c75b24f0ecfc81f8ba4afaff1807aef98 100644 (file)
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2446,9 +2446,12 @@ because it recognizes abbreviations even as part of the name.
 @end defun
 
 @defun file-parent-directory filename
-This function returns the parent directory of @var{filename}.  If
-@var{filename} is at the top level, return @code{nil}.  @var{filename}
-can be relative to @code{default-directory}.
+This function returns the directory name of the parent directory of
+@var{filename}.  If @var{filename} is at the root directory of the
+filesystem, it returns @code{nil}.  A relative @var{filename} is
+assumed to be relative to @code{default-directory}, and the return
+value will also be relative in that case.  If the return value is
+non-@code{nil}, it ends in a slash.
 @end defun
 
 @node File Name Expansion

diff --git a/lisp/files.el b/lisp/files.el
index b952b08ff4783285039744b8a7c5f07a5c05f832..185aae164d332ace1df3f5aa74df3f972a9db41c 100644 (file)
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -5146,9 +5146,10 @@ On most systems, this will be true:
     components))
 
 (defun file-parent-directory (filename)
-  "Return the parent directory of FILENAME.
-If FILENAME is at the top level, return nil.  FILENAME can be
-relative to `default-directory'."
+  "Return the directory name of the parent directory of FILENAME.
+If FILENAME is at the root of the filesystem, return nil.
+If FILENAME is relative, it is interpreted to be relative
+to `default-directory', and the result will also be relative."
   (let* ((expanded-filename (expand-file-name filename))
          (parent (file-name-directory (directory-file-name expanded-filename))))
     (cond