From: Eli Zaretskii <eliz@gnu.org>
Date: Mon, 4 Jul 2022 11:59:58 +0000 (+0300)
Subject: ; Fix documentation of 'file-parent-directory'
X-Git-Tag: emacs-29.0.90~1447^2~1206
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=603de9a38ef92bb6583973e6c874f551c185d3bd;p=emacs.git

; 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 ee4e1ec4d96..986fb22c75b 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 b952b08ff47..185aae164d3 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