[Emacs-diffs] emacs-25 1db9d8b: Clarify documentation of 'modify-frame-parameters'

[Eli Zaretskii]

branch: emacs-25
commit 1db9d8bd0fb41bda3cc8027ec0cf27aade71b400
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Clarify documentation of 'modify-frame-parameters'
    
    * doc/lispref/frames.texi (Parameter Access): Clarify what "ignored
    PARMs" mean for 'modify-frame-parameters'.
    
    * src/frame.c (Fmodify_frame_parameters): Clarify what "ignored
    PARMs" mean for this function.  (Bug#22104)
---
 doc/lispref/frames.texi |   18 ++++++++++++------
 src/frame.c             |   11 +++++++----
 2 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 3c1a87a..b6f0720 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1001,12 +1001,18 @@ parameters of @var{frame} and their values.  If 
@var{frame} is
 @end defun
 
 @defun modify-frame-parameters frame alist
-This function alters the parameters of frame @var{frame} based on the
-elements of @var{alist}.  Each element of @var{alist} has the form
address@hidden(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
-parameter.  If you don't mention a parameter in @var{alist}, its value
-doesn't change.  If @var{frame} is @code{nil}, it defaults to the selected
-frame.
+This function alters the frame @var{frame} based on the elements of
address@hidden  Each element of @var{alist} has the form
address@hidden(@var{parm} . @var{value})}, where @var{parm} is a symbol naming
+a parameter.  If you don't mention a parameter in @var{alist}, its
+value doesn't change.  If @var{frame} is @code{nil}, it defaults to
+the selected frame.
+
+Some parameters are only meaningful for frames on certain kinds of
+display (@pxref{Frames}).  If @var{alist} includes parameters that are
+not meaningful for the @var{frame}'s display, this function will
+change its value in the frame's parameter list, but will otherwise
+ignore it.
 @end defun
 
 @defun set-frame-parameter frame parm value
diff --git a/src/frame.c b/src/frame.c
index c388986..4897052 100644
--- a/src/frame.c
+++ b/src/frame.c
@@ -2641,13 +2641,16 @@ If FRAME is nil, describe the currently selected frame. 
 */)
 
 DEFUN ("modify-frame-parameters", Fmodify_frame_parameters,
        Smodify_frame_parameters, 2, 2, 0,
-       doc: /* Modify the parameters of frame FRAME according to ALIST.
+       doc: /* Modify FRAME according to new values of its parameters in ALIST.
 If FRAME is nil, it defaults to the selected frame.
 ALIST is an alist of parameters to change and their new values.
 Each element of ALIST has the form (PARM . VALUE), where PARM is a symbol.
-The meaningful PARMs depend on the kind of frame.
-Undefined PARMs are ignored, but stored in the frame's parameter list
-so that `frame-parameters' will return them.
+Which PARMs are meaningful depends on the kind of frame.
+The meaningful parameters are acted upon, i.e. the frame is changed
+according to their new values, and are also stored in the frame's
+parameter list so that `frame-parameters' will return them.
+PARMs that are not meaningful are still stored in the frame's parameter
+list, but are otherwise ignored.
 
 The value of frame parameter FOO can also be accessed
 as a frame-local binding for the variable FOO, if you have