emacs-28 0cbcaf5119: ; Yet another doc fix for 'ff-other-file-alist' (bug#57325)

[Eli Zaretskii]

branch: emacs-28
commit 0cbcaf5119d36093882f0c414c4c586186ef77b2
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Yet another doc fix for 'ff-other-file-alist' (bug#57325)
---
 lisp/find-file.el | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/lisp/find-file.el b/lisp/find-file.el
index e9aba883ae..aaabec11e8 100644
--- a/lisp/find-file.el
+++ b/lisp/find-file.el
@@ -193,17 +193,26 @@ The value could be an alist or a symbol whose value is an 
alist.
 Each element of the alist has the form
 
    (REGEXP (EXTENSION...))
-or
-   (REGEXP FUNCTION)
 
 where REGEXP is the regular expression matching a file's extension,
-EXTENSIONs is the list of literal file-name extensions to search for,
-and FUNCTION is a function of one argument, the current file's name,
-that returns the list of extensions to search for.
-The list of extensions should contain the most used extensions before the
-others, since the search algorithm searches sequentially through each
-directory specified in `ff-search-directories'.  If a file is not found,
-a new one is created with the first matching extension (`.cc' yields `.hh').
+and EXTENSIONs is the list of literal file-name extensions to search
+for.  The list of extensions should contain the most used extensions
+before the others, since the search algorithm searches sequentially
+through each directory specified in `ff-search-directories'.
+
+Alist elements can also be of the form
+
+   (REGEXP FUNCTION)
+
+where FUNCTION is a function of one argument, the current file's name,
+that returns the list of possible names of the corresponding files, with
+or without leading directories.  Note the difference: FUNCTION returns
+the list of file names, not their extensions.  This is for the case when
+REGEXP is not enough to determine the file name of the other file.
+
+If a file is not found, a new one is created with the first
+matching extension or name (e.g., `.cc' yields `.hh').
+
 This alist should be set by the major mode.
 
 Note: if an element of the alist names a FUNCTION as its cdr, that