master a2dd9d683a: Merge from origin/emacs-28

[Stefan Kangas]

branch: master
commit a2dd9d683a02525183b5e692e42622c65639dda8
Merge: 9d47364634 32ef7550ed
Author: Stefan Kangas <stefankangas@gmail.com>
Commit: Stefan Kangas <stefankangas@gmail.com>

    Merge from origin/emacs-28
    
    32ef7550ed ; Improve documentation of 'file-in-directory-p'
---
 doc/lispref/files.texi | 19 +++++++++++--------
 lisp/files.el          |  7 ++++---
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index e1aa2de523..0e8efa3297 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1253,14 +1253,6 @@ the @samp{smb} method.  For all other connection 
methods, runtime
 tests are performed.
 @end defun
 
-@defun file-in-directory-p file dir
-This function returns @code{t} if @var{file} is a file in directory
-@var{dir}, or in a subdirectory of @var{dir}.  It also returns
-@code{t} if @var{file} and @var{dir} are the same directory.  It
-compares the truenames of the two directories.  If @var{dir} does not
-name an existing directory, the return value is @code{nil}.
-@end defun
-
 @defun vc-responsible-backend file
 This function determines the responsible VC backend of the given
 @var{file}.  For example, if @file{emacs.c} is a file tracked by Git,
@@ -3100,6 +3092,17 @@ is called with one argument (the file or directory) and 
should return
 non-@code{nil} if that directory is the one it is looking for.
 @end defun
 
+@cindex parent directory of file
+@cindex ancestor directory of file
+@cindex file, ancestor directory of
+@defun file-in-directory-p file dir
+This function returns @code{t} if @var{file} is a file in directory
+@var{dir}, or in a subdirectory of @var{dir}.  It also returns
+@code{t} if @var{file} and @var{dir} are the same directory.  It
+compares the truenames of the two directories.  If @var{dir} does not
+name an existing directory, the return value is @code{nil}.
+@end defun
+
 @defun directory-files-and-attributes directory &optional full-name 
match-regexp nosort id-format count
 This is similar to @code{directory-files} in deciding which files
 to report on and how to report their names.  However, instead
diff --git a/lisp/files.el b/lisp/files.el
index 43c5d7d1da..94d110f0b7 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -6344,9 +6344,10 @@ If FILE1 or FILE2 does not exist, the return value is 
unspecified."
             (equal f1-attr f2-attr))))))
 
 (defun file-in-directory-p (file dir)
-  "Return non-nil if FILE is in DIR or a subdirectory of DIR.
-A directory is considered to be \"in\" itself.
-Return nil if DIR is not an existing directory."
+  "Return non-nil if DIR is a parent directory of FILE.
+Value is non-nil if FILE is inside DIR or inside a subdirectory of DIR.
+A directory is considered to be a \"parent\" of itself.
+DIR must be an existing directory, otherwise the function returns nil."
   (let ((handler (or (find-file-name-handler file 'file-in-directory-p)
                      (find-file-name-handler dir  'file-in-directory-p))))
     (if handler