Make `find-function-source-path' into obsolete alias

* lisp/finder.el (finder-commentary): Adjust usage.

* lisp/emacs-lisp/find-func.el (find-function-source-path): Made
into obsolete alias (bug#50508).
(find-library-source-path): New name.
(find-library-name, find-library, find-function-noselect)
(find-variable-noselect, find-definition-noselect): Adjust usage
and update doc strings.

3 files changed, 34 insertions, 31 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 279bb17bbb5..5809716868a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3384,6 +3384,19 @@ In Emacs 24.3, the variable 'dbus-event-error-hooks' was renamed to
 The old names, which were kept as obsolete aliases of the new names,
 have now been removed.
 
+---
+** 'find-function-source-path' renamed and re-documented.
+The 'find-function' command (and various related commands) were
+documented to respect 'find-function-source-path', and to search for
+objects in files specified by that variable.  It's unclear when this
+actually changed, but at some point (perhaps decades ago) these
+commands started using 'load-history' to determine where symbols had
+been defined (which is much faster).  The doc strings of all the
+affected function has been updated.  'find-function-source-path' was
+still being used by 'find-library' and related commands, so the
+variable has been renamed to 'find-library-source-path', and
+'find-function-source-path' is now an obsolete variable alias.
+
 
 * Lisp Changes in Emacs 28.1
 
diff --git a/lisp/emacs-lisp/find-func.el b/lisp/emacs-lisp/find-func.el
index 4bbcf453569..303039d6534 100644
--- a/lisp/emacs-lisp/find-func.el
+++ b/lisp/emacs-lisp/find-func.el
@@ -145,13 +145,16 @@ in which case the function is called with one argument (the object
 we're looking for) and it should search for it.")
 (put 'find-function-regexp-alist 'risky-local-variable t)
 
-(defcustom find-function-source-path nil
-  "The default list of directories where `find-function' searches.
+(define-obsolete-variable-alias 'find-function-source-path
+  'find-library-source-path "28.1")
+(defcustom find-library-source-path nil
+  "The default list of directories where `find-library' searches.
 
-If this variable is nil then `find-function' searches `load-path' by
+If this variable is nil then `find-library' searches `load-path' by
 default."
   :type '(repeat directory)
-  :group 'find-function)
+  :group 'find-function
+  :version "28.1")
 
 (defcustom find-function-recenter-line 1
   "The window line-number from which to start displaying a symbol definition.
@@ -200,20 +203,20 @@ LIBRARY should be a string (the name of the library)."
     (setq library (gethash (file-name-nondirectory library) comp-eln-to-el-h))))
   (or
    (locate-file library
-                (or find-function-source-path load-path)
+                (or find-library-source-path load-path)
                 (find-library-suffixes))
    (locate-file library
-                (or find-function-source-path load-path)
+                (or find-library-source-path load-path)
                 load-file-rep-suffixes)
    (when (file-name-absolute-p library)
      (let ((rel (find-library--load-name library)))
        (when rel
          (or
           (locate-file rel
-                       (or find-function-source-path load-path)
+                       (or find-library-source-path load-path)
                        (find-library-suffixes))
           (locate-file rel
-                       (or find-function-source-path load-path)
+                       (or find-library-source-path load-path)
                        load-file-rep-suffixes)))))
    (find-library--from-load-history library)
    (signal 'file-error (list "Can't find library" library))))
@@ -286,7 +289,10 @@ TYPE should be nil to find a function, or `defvar' to find a variable."
 (defun find-library (library)
   "Find the Emacs Lisp source of LIBRARY.
 
-Interactively, prompt for LIBRARY using the one at or near point."
+Interactively, prompt for LIBRARY using the one at or near point.
+
+This function searches `find-library-source-path' if non-nil, and
+`load-path' otherwise."
   (interactive (list (read-library-name)))
   (prog1
       (switch-to-buffer (find-file-noselect (find-library-name library)))
@@ -297,9 +303,9 @@ Interactively, prompt for LIBRARY using the one at or near point."
   "Read and return a library name, defaulting to the one near point.
 
 A library name is the filename of an Emacs Lisp library located
-in a directory under `load-path' (or `find-function-source-path',
+in a directory under `load-path' (or `find-library-source-path',
 if non-nil)."
-  (let* ((dirs (or find-function-source-path load-path))
+  (let* ((dirs (or find-library-source-path load-path))
          (suffixes (find-library-suffixes))
          (table (apply-partially 'locate-file-completion-table
                                  dirs suffixes))
@@ -521,11 +527,7 @@ the buffer, returns (BUFFER).
 
 If FUNCTION is a built-in function, this function normally
 attempts to find it in the Emacs C sources; however, if LISP-ONLY
-is non-nil, signal an error instead.
-
-If the file where FUNCTION is defined is not known, then it is
-searched for in `find-function-source-path' if non-nil, otherwise
-in `load-path'."
+is non-nil, signal an error instead."
   (if (not function)
     (error "You didn't specify a function"))
   (let ((func-lib (find-function-library function lisp-only t)))
@@ -589,8 +591,6 @@ near point (selected by `function-called-at-point') in a buffer and
 places point before the definition.
 Set mark before moving, if the buffer already existed.
 
-The library where FUNCTION is defined is searched for in
-`find-function-source-path', if non-nil, otherwise in `load-path'.
 See also `find-function-recenter-line' and `find-function-after-hook'."
   (interactive (find-function-read))
   (find-function-do-it function nil 'switch-to-buffer))
@@ -617,10 +617,7 @@ See `find-function' for more details."
 
 Finds the library containing the definition of VARIABLE in a buffer and
 the point of the definition.  The buffer is not selected.
-If the variable's definition can't be found in the buffer, return (BUFFER).
-
-The library where VARIABLE is defined is searched for in FILE or
-`find-function-source-path', if non-nil, otherwise in `load-path'."
+If the variable's definition can't be found in the buffer, return (BUFFER)."
   (if (not variable)
       (error "You didn't specify a variable")
     (let ((library (or file
@@ -638,8 +635,6 @@ places point before the definition.
 
 Set mark before moving, if the buffer already existed.
 
-The library where VARIABLE is defined is searched for in
-`find-function-source-path', if non-nil, otherwise in `load-path'.
 See also `find-function-recenter-line' and `find-function-after-hook'."
   (interactive (find-function-read 'defvar))
   (find-function-do-it variable 'defvar 'switch-to-buffer))
@@ -666,10 +661,7 @@ See `find-variable' for more details."
 If the definition can't be found in the buffer, return (BUFFER).
 TYPE says what type of definition: nil for a function, `defvar' for a
 variable, `defface' for a face.  This function does not switch to the
-buffer nor display it.
-
-The library where SYMBOL is defined is searched for in FILE or
-`find-function-source-path', if non-nil, otherwise in `load-path'."
+buffer nor display it."
   (cond
    ((not symbol)
     (error "You didn't specify a symbol"))
@@ -693,8 +685,6 @@ places point before the definition.
 
 Set mark before moving, if the buffer already existed.
 
-The library where FACE is defined is searched for in
-`find-function-source-path', if non-nil, otherwise in `load-path'.
 See also `find-function-recenter-line' and `find-function-after-hook'."
   (interactive (find-function-read 'defface))
   (find-function-do-it face 'defface 'switch-to-buffer))
diff --git a/lisp/finder.el b/lisp/finder.el
index 555506db22f..c2b9a6d0ef9 100644
--- a/lisp/finder.el
+++ b/lisp/finder.el
@@ -379,7 +379,7 @@ FILE should be in a form suitable for passing to `locate-library'."
    (list
     (completing-read "Library name: "
                      (apply-partially 'locate-file-completion-table
-                                      (or find-function-source-path load-path)
+                                      (or find-library-source-path load-path)
                                       (find-library-suffixes)))))
   (let ((str (lm-commentary (find-library-name file))))
     (or str (error "Can't find any Commentary section"))