; Fix documentation of a recent commit

* etc/NEWS:
* doc/lispref/loading.texi (How Programs Do Loading): Document the
new variable and function.

* src/lread.c (load-path-filter-function):
* lisp/startup.el (load-path-filter-cache-directory-files)
(load-path-filter--cache): Doc fixes.

(cherry picked from commit da174e4a15229ae498713444e70c382d7e0e90cd)

diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index c0cf5de8a7f8e7b29dc5c312ed742ac68cb851fc..6a650f443c386b187679171ae903071afa9df3d2 100644 (file)
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -221,6 +221,26 @@ Functions}.
 Instead of using this variable, it is cleaner to use another, newer
 feature: to pass the function as the @var{read-function} argument to
 @code{eval-region}.  @xref{Definition of eval-region,, Eval}.
+@end defvar
+
+@defun load-path-filter-cache-directory-files path filename suffixes
+This function filters @var{path} to remove any directories that could
+not hold @var{filename} with any of @var{suffixes}, and returns the
+filtered list of directories.  The function caches the directories it
+scans and the files inside them, and uses the cache in subsequent calls,
+which speeds up repeated lookups of files in @var{path}.
+@end defun
+
+@defvar load-path-filter-function
+If this variable names a function, @code{load} will call that function
+when it scans @code{load-path} to find files.  The function will be
+called with 3 arguments: the value of @code{load-path}, @var{filename},
+the name of a file being looked up as passed to @code{load}, and a list
+of suffixes to append to @var{filename}.  It should return a shorter
+list of directories where @var{filename} can reside, thus making the
+lookup faster.  The function
+@code{load-path-filter-cache-directory-files} is a good candidate to be
+such a function.
 @end defvar
 
   For information about how @code{load} is used in building Emacs, see

diff --git a/lisp/startup.el b/lisp/startup.el
index 29a04bef706d24edde3ecc6d349112b5b1c7ba0f..9caefe8a6d3c8d71273c36f21e179ca2567fcb6d 100644 (file)
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -1100,19 +1100,25 @@ the `--debug-init' option to view a complete error backtrace."
 (defvar load-path-filter--cache nil
   "A cache used by `load-path-filter-cache-directory-files'.
 
-This is an alist.  The car of each entry is a list of load suffixes,
+The value is an alist.  The car of each entry is a list of load suffixes,
 such as returned by `get-load-suffixes'.  The cdr of each entry is a
-cons whose car is an optimized regex matching those suffixes at the end
-of a string, and whose cdr is a hashtable mapping directories to files
-in that directory which end with one of the suffixes.")
+cons whose car is an `regex-opt' optimized regex matching those suffixes
+at the end of a string, and whose cdr is a hash-table mapping directories
+to files in those directories which end with one of the suffixes.
+The hash-table uses `equal' as its key comparison function.")
 
 (defun load-path-filter-cache-directory-files (path file suffixes)
-  "Filter PATH to only directories which might contain FILE with SUFFIXES.
+  "Filter PATH to leave only directories which might contain FILE with SUFFIXES.
 
-Doesn't filter if FILE is an absolute file name or if FILE is a relative
-file name with more than one component.
+PATH should be a list of directories such as `load-path'.
+Returns a copy of PATH with any directories that cannot contain FILE
+with SUFFIXES removed from it.
+Doesn't filter PATH if FILE is an absolute file name or if FILE is
+a relative file name with leading directories.
 
-Caches directory contents in `load-path-filter--cache'."
+Caches contents of directories in `load-path-filter--cache'.
+
+This function is called from `load' via `load-path-filter-function'."
   (if (file-name-directory file)
       ;; FILE has more than one component, don't bother filtering.
       path

diff --git a/src/lread.c b/src/lread.c
index ed481c197215c5376bcf4d116f8b026bb752ddf6..9b902532393417bf04f2daaafe20be0b3979c04c 100644 (file)
--- a/src/lread.c
+++ b/src/lread.c
@@ -6113,14 +6113,15 @@ through `require'.  */);
 
   DEFVAR_LISP ("load-path-filter-function",
               Vload_path_filter_function,
-              doc: /* Non-nil means to call this function to filter `load-path' for `load'.
+              doc: /* If non-nil, a function to filter `load-path' for `load'.
 
-When load is called, this function is called with three arguments: the
-current value of `load-path' (a list of directories), the FILE argument
-to load, and the current load-suffixes.
+If this variable is a function, it is called when `load' is about to
+search for a file along `load-path'.  This function is called with three
+arguments: the current value of `load-path' (a list of directories),
+the FILE argument to `load', and the current list of load-suffixes.
 
-It should return a list of directories, which `load' will use instead of
-`load-path'.  */);
+It should return a (hopefully shorter) list of directories, which `load'
+will use instead of `load-path' to look for the file to load.  */);
   Vload_path_filter_function = Qnil;
 
   /* Vsource_directory was initialized in init_lread.  */