From 84f431224cdc1ee65b4662f3eb55f4da46066e3e Mon Sep 17 00:00:00 2001
From: Stefan Monnier <monnier@iro.umontreal.ca>
Date: Fri, 27 May 2016 12:33:57 -0400
Subject: [PATCH] * lisp/subr.el (definition-prefixes): Expand docstring

* lisp/emacs-lisp/autoload.el (autoload--split-prefixes):
Remove unused function.
---
 etc/NEWS                    |  4 ++++
 lisp/emacs-lisp/autoload.el | 16 +++++++---------
 lisp/subr.el                | 11 ++++++++++-
 3 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 56f0ef8de2..b2e42e3f91 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -385,6 +385,10 @@ function 'check-declare-errmsg' has been removed.
 
 * Lisp Changes in Emacs 25.2
 
+** New var `definition-prefixes' is a hashtable mapping prefixes to the
+files where corresponding definitions can be found.  This can be used
+to fetch definitions that are not yet loaded, for example for `C-h f'.
+
 ** New var syntax-ppss-table to control the syntax-table used in syntax-ppss.
 
 +++
diff --git a/lisp/emacs-lisp/autoload.el b/lisp/emacs-lisp/autoload.el
index 80f5c28f3e..11316f1d9d 100644
--- a/lisp/emacs-lisp/autoload.el
+++ b/lisp/emacs-lisp/autoload.el
@@ -513,15 +513,6 @@ Return non-nil in the case where no autoloads were added at point."
          (t (setcdr cell (cons tail (cdr cell)))))))
     prefixes))
 
-(defun autoload--split-prefixes (prefixes)
-  (apply #'nconc
-         (mapcar (lambda (cell)
-                   (let ((prefix (car cell)))
-                     (mapcar (lambda (cell)
-                               (cons (concat prefix (car cell)) (cdr cell)))
-                             (autoload--split-prefixes-1 (cdr cell)))))
-                 prefixes)))
-
 (defvar autoload-compute-prefixes t
   "If non-nil, autoload will add code to register the prefixes used in a file.
 Standard prefixes won't be registered anyway.  I.e. if a file \"foo.el\" defines
@@ -538,6 +529,13 @@ cost more memory use).")
 (defvar autoload-popular-prefixes nil)
 
 (defun autoload--make-defs-autoload (defs file)
+  ;; FIXME: avoid redundant entries.  E.g. opascal currently has
+  ;; "opascal-" "opascal--literal-start-re" "opascal--syntax-propertize"
+  ;; where only the first one should be kept.
+  ;; FIXME: Avoid keeping too-long-prefixes.  E.g. ob-scheme currently has
+  ;; "org-babel-scheme-" "org-babel-default-header-args:scheme"
+  ;; "org-babel-expand-body:scheme" "org-babel-execute:scheme".
+
   ;; Remove the defs that obey the rule that file foo.el (or
   ;; foo-mode.el) uses "foo-" as prefix.
   ;; FIXME: help--symbol-completion-table still doesn't know how to use
diff --git a/lisp/subr.el b/lisp/subr.el
index 7cbf0063ac..44d7eaccf0 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -5155,7 +5155,16 @@ as a list.")
 
 (defvar definition-prefixes (make-hash-table :test 'equal)
   "Hash table mapping prefixes to the files in which they're used.
-This can be used to automatically fetch not-yet-loaded definitions.")
+This can be used to automatically fetch not-yet-loaded definitions.
+More specifically, if there is a value of the form (FILES...) for a string PREFIX
+it means that the FILES define variables or functions with names that start
+with PREFIX.
+
+Note that it does not imply that all definitions starting with PREFIX can
+be found in those files.  E.g. if prefix is \"gnus-article-\" there might
+still be definitions of the form \"gnus-article-toto-titi\" in other files, which would
+presumably appear in this table under another prefix such as \"gnus-\"
+or \"gnus-article-toto-\".")
 
 (defun register-definition-prefixes (file prefixes)
   "Register that FILE uses PREFIXES."
-- 
2.39.2