Clarify documentation of 'face-spec-set'

* lisp/faces.el (face-spec-set): Clarify the description of
SPEC-TYPE in the doc string.

* doc/lispref/display.texi (Defining Faces): Clarify the
description of 'face-spec-set's SPEC-TYPE argument.  (Bug#27246)

2 files changed, 21 insertions, 16 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index aa75dcf5a0a..4a895f74a5d 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2531,16 +2531,20 @@ This function also defines @var{face} as a valid face name if it is
 not already one, and (re)calculates its attributes on existing frames.
 
 @cindex override spec @r{(for a face)}
-The argument @var{spec-type} determines which spec to set.  If it is
-@code{nil} or @code{face-override-spec}, this function sets the
-@dfn{override spec}, which overrides over all other face specs on
-@var{face}.  If it is @code{customized-face} or @code{saved-face},
-this function sets the customized spec or the saved custom spec.  If
-it is @code{face-defface-spec}, this function sets the default face
-spec (the same one set by @code{defface}).  If it is @code{reset},
-this function clears out all customization specs and override specs
-from @var{face} (in this case, the value of @var{spec} is ignored).
-Any other value of @var{spec-type} is reserved for internal use.
+The optional argument @var{spec-type} determines which spec to set.
+If it is omitted or @code{nil} or @code{face-override-spec}, this
+function sets the @dfn{override spec}, which overrides face specs on
+@var{face} of all the other types mentioned below.  This is useful
+when calling this function outside of Custom code.  If @var{spec-type}
+is @code{customized-face} or @code{saved-face}, this function sets the
+customized spec or the saved custom spec, respectively.  If it is
+@code{face-defface-spec}, this function sets the default face spec
+(the same one set by @code{defface}).  If it is @code{reset}, this
+function clears out all customization specs and override specs from
+@var{face} (in this case, the value of @var{spec} is ignored).  The
+effect of any other value of @var{spec-type} on the face specs is
+reserved for internal use, but the function will still define
+@var{face} itself and recalculate its attributes, as described above.
 @end defun
 
 @node Attribute Functions
diff --git a/lisp/faces.el b/lisp/faces.el
index 1f9b3974c72..9a8a1344caf 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -1667,7 +1667,7 @@ is given, in which case return its value instead."
            face--attributes-unspecified)))
 
 (defun face-spec-set (face spec &optional spec-type)
-  "Set the face spec SPEC for FACE.
+  "Set the FACE's spec SPEC, define FACE, and recalculate its attributes.
 See `defface' for the format of SPEC.
 
 The appearance of each face is controlled by its specs (set via
@@ -1678,10 +1678,11 @@ This function also defines FACE as a valid face name if it is not
 already one, and (re)calculates its attributes on existing
 frames.
 
-The argument SPEC-TYPE determines which spec to set:
-  nil or `face-override-spec' means the override spec (which is
-    usually what you want if calling this function outside of
-    Custom code);
+The optional argument SPEC-TYPE determines which spec to set:
+  nil, omitted or `face-override-spec' means the override spec,
+    which overrides all the other types of spec mentioned below
+    (this is usually what you want if calling this function
+    outside of Custom code);
   `customized-face' or `saved-face' means the customized spec or
     the saved custom spec;
   `face-defface-spec' means the default spec
@@ -1689,7 +1690,7 @@ The argument SPEC-TYPE determines which spec to set:
   `reset' means to ignore SPEC, but clear the `customized-face'
     and `face-override-spec' specs;
 Any other value means not to set any spec, but to run the
-function for its other effects."
+function for defining FACE and recalculating its attributes."
   (if (get face 'face-alias)
       (setq face (get face 'face-alias)))
   ;; Save SPEC to the relevant symbol property.