bug#5105: 23.1; doc string of facemenu-set-face

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

> >> > What?  Why are you arbitrarily deciding that?  Why not 
> >> > assume that allowing a string is a good thing, a
> >> > purposeful design decision?
> >>
> >> Because a good programmer knows that it's obviously not a 
> >> good idea to encourage the caller to use a string here.
> >
> > It might be obvious to what you call good programmers, but 
> > how about giving a _reason_, for us mere mortals?
> 
> How 'bout the other way around: give me a reason to accept strings.

You're the one claiming that there is a good (even _obvious_) reason not to.
What's the reason, if it's so obvious?

> >>> We have many places in Emacs where we allow an arg to be
> >>> either a thing or its name.  Think of all of the BUFFER args
> >>> that can be a buffer or a buffer name.
> >
> > What do the "good programmers" say about the design in 
> > those cases?  Is it "obviously not a good idea" also?
> 
> Very often, yes it's also a bad idea.

Why?  And when? ("Very often" doesn't say much - how about a specific context
where it is a bad idea, since there are supposedly so many.)

How about a reason or two to back up all the hand-waving claims about "good" and
"bad"?

> At least for buffers we have a guarantee that there is a
> one-to-one mapping between (live) buffers and buffer names,
> so for buffers it's a bit less bad.

"Less bad"?  You haven't said what is bad about it.

And what about faces?  Can a given face have two different names?  We have
`face-name' the same way we have `buffer-name'.  At least there is nothing
documented AFAICT about `face-name' being a relation and not a function.

If F is a face, under what circumstances will (face-name F) give different names
at different times?