Merge from origin/emacs-25

d1efbaf Fix documentation of completion functions
65c96cc Clarify documentation of 'font-lock-maximum-decoration'
2ad3d01 * doc/misc/cl.texi (Usage): Add some more details.
b49cb0a Fbackward_prefix_chars: stay within buffer bounds

3 files changed, 16 insertions, 5 deletions

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 3f5aac1c2f..738d72d046 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -853,9 +853,15 @@ to alter the amount of fontification applied by Font Lock mode, for
 major modes that support this feature.  The value should be a number
 (with 1 representing a minimal amount of fontification; some modes
 support levels as high as 3); or @code{t}, meaning ``as high as
-possible'' (the default).  You can also specify different numbers for
-particular major modes; for example, to use level 1 for C/C++ modes,
-and the default level otherwise, use the value
+possible'' (the default).  To be effective for a given file buffer,
+the customization of @code{font-lock-maximum-decoration} should be
+done @emph{before} the file is visited; if you already have the file
+visited in a buffer when you customize this variable, kill the buffer
+and visit the file again after the customization.
+
+You can also specify different numbers for particular major modes; for
+example, to use level 1 for C/C++ modes, and the default level
+otherwise, use the value
 
 @example
 '((c-mode . 1) (c++-mode . 1)))
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index e6d8f8a4c7..8d5347556e 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -750,8 +750,8 @@ list contains elements of any other type, those are ignored.
 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
 of all symbols in the obarray form the set of permissible completions.
 
-If @var{collection} is a hash table, then the keys that are strings
-are the possible completions.  Other keys are ignored.
+If @var{collection} is a hash table, then the keys that are strings or
+symbols are the possible completions.  Other keys are ignored.
 
 You can also use a function as @var{collection}.  Then the function is
 solely responsible for performing completion; @code{try-completion}
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index a98d0ac455..c62fa727c1 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -148,6 +148,11 @@ the beginning:
 You may wish to add such a statement to your init file, if you
 make frequent use of features from this package.
 
+Code that only uses macros from this package can enclose the above in
+@code{eval-when-compile}.  Internally, this library is divided into
+several files, @pxref{Organization}.  Your code should only ever load
+the main @file{cl-lib} file, which will load the others as needed.
+
 @node Organization
 @section Organization