Some doc fixes for completion-hilit-commonality and friends

* lisp/minibuffer.el (completions-first-difference)
(completions-common-part, completion-hilit-commonality): Doc fixes.

2 files changed, 21 insertions, 5 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 6d8c296d366..65dbcf65e6e 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,8 @@
+2014-02-28  Glenn Morris  <rgm@gnu.org>
+
+        * minibuffer.el (completions-first-difference)
+        (completions-common-part, completion-hilit-commonality): Doc fixes.
+
 2014-02-28  Karl Berry  <karl@gnu.org>
 
         * info.el (Info-mode-map): Add H for describe-mode,
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 88ab94f0521..c888721fb49 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -1576,15 +1576,26 @@ See also `display-completion-list'.")
 
 (defface completions-first-difference
   '((t (:inherit bold)))
-  "Face added on the first uncommon character in completions in *Completions* buffer.")
+  "Face for the first uncommon character in completions.
+See also the face `completions-common-part'.")
 
 (defface completions-common-part '((t nil))
-  "Face added on the common prefix substring in completions in *Completions* buffer.
-The idea of `completions-common-part' is that you can use it to
-make the common parts less visible than normal, so that the rest
-of the differing parts is, by contrast, slightly highlighted.")
+  "Face for the common prefix substring in completions.
+The idea of this face is that you can use it to make the common parts
+less visible than normal, so that the differing parts are emphasized
+by contrast.
+See also the face `completions-first-difference'.")
 
 (defun completion-hilit-commonality (completions prefix-len base-size)
+  "Apply font-lock highlighting to a list of completions, COMPLETIONS.
+PREFIX-LEN is an integer.  BASE-SIZE is an integer or nil (meaning zero).
+
+This adds the face `completions-common-part' to the first
+\(PREFIX-LEN - BASE-SIZE) characters of each completion, and the face
+`completions-first-difference' to the first character after that.
+
+It returns a list with font-lock properties applied to each element,
+and with BASE-SIZE appended as the last element."
   (when completions
     (let ((com-str-len (- prefix-len (or base-size 0))))
       (nconc