bug#22104: 25.1.50; doc string of `modify-frame-parameters'

[Drew Adams <drew.adams@oracle.com>]

> > > > This part of the doc string is unclear:
> > > >
> > > >  Undefined PARMs are ignored, but stored in the frame's parameter
> list
> > > >  so that 'frame-parameters' will return them.
> > > >
> > > > What does "ignored" mean here?  It can only mean (?) ignored by
> > > > `modify-parameters', but what does that mean, operationally?
> > >
> > > It means they have no effect beyond being stored in the parameter
> > > list.  I will clarify that.
> >
> > But I still don't understand, from that description.  What else
> > does `modify-frame-parameters' ever do, besides store them in the
> > parameter list?
> 
> Quite a few parameters require modify-frame-parameters to call some
> API in order to put the parameter in effect.  For example,
> background-color -- just storing the new value won't magically change
> the color, would it?
> 
> IOW, modify-frame-parameters is not just for altering the params
> alist, it is primarily for changing the frame according to the changed
> parameters; it records the parameters in effect in the alist mostly as
> a side effect.
> 
> Yes, "modify the frame parameters" is ambiguous.

OK, so I guess the point is that unrecognized (perhaps a better term than "undefined", here) parameters are simply stored in the frame's parameter
list.  No extra handling is done.

I think that statement can just be removed.  No one would guess that
any special, additional action would be undertaken for a parameter that
Emacs does not recognize.  Talking about this just confuses readers.

Users should know that they can add any parameters they want, which
are unknown to Emacs.  But because Emacs knows nothing about them it
is up to a user to provide any expected behavior for them.

It is important to say that users can add their own parameters.

And I guess it is helpful to add that Emacs does not do anything
with them (unless the user programs it to do so).  But if we can't
do that without confusing readers more, then this addition should
be dropped, IMO.