; 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.

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

etc/NEWS

@@ -2213,6 +2213,13 @@ Like 'static-if', these macros evaluate their condition at
 macro-expansion time and are useful for writing code that can work
 across different Emacs versions.
 
++++
+** New feature to speed up repeated lookup of Lisp files in 'load-path'.
+If the new variable 'load-path-filter-function' is set to the new
+function 'load-path-filter-cache-directory-files', calling 'load' will
+cache the directories it scans and their files, and the following
+lookups should be faster.
+
 ** Lexical binding
 
 ---

lisp/startup.el

@@ -1146,19 +1146,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

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.  */