master 603de9a38e: ; Fix documentation of 'file-parent-directory'

[Eli Zaretskii]

branch: master
commit 603de9a38ef92bb6583973e6c874f551c185d3bd
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; 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)
---
 doc/lispref/files.texi | 9 ++++++---
 lisp/files.el          | 7 ++++---
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index ee4e1ec4d9..986fb22c75 100644
--- 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 b952b08ff4..185aae164d 100644
--- 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