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

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

> > I think that statement can just be removed.
> 
> I believe this feature is used to make "frame-local" variables.  So
> removing that sentence will lose information.

How so? Is that explained somewhere (e.g. in the manual)?
I know nothing about this, and the statement in the doc string
leaves me clueless.

> > No one would guess that any special, additional action would be
> > undertaken for a parameter that Emacs does not recognize.
> 
> But it could well barf for such a parameter, at least in principle.
> So that sentence does add useful information.

Really?  That would be a bug, no?  Why should it not accept a
user-supplied parameter?

As for that sentence adding useful info - I cannot agree.
Frankly, it just confuses me.

When you say that Emacs might barf, given a parameter it doesn't
recognize, that is not at all conveyed by a statement that Emacs
doesn't do anything with it except store it as a frame parameter.

Sorry, but this is not at all clear to me now - neither what
Emacs really does (possibly barfs?) nor how that statement is
supposed to help understanding (including about frame-local vars
and the possibility that Emacs might barf).

> > 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.
> 
> Oh, I think we have all the technology necessary to say that in a way
> that won't confuse users.

OK, I trust you will; thanks.  You've heard my concerns/confusions,
at least.  Maybe they will help you decide what to say, and how.