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

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

> >> > The doc string should say explicitly what the args are. In 
> >> > particular, it should say that FACE can be a string or a symbol.
> >> 
> >> What does FACE mean if FACE is a string?
> >
> > You tell me.  And other users.
> >
> > The answer is apparently...the face name.
> > E.g., you can use the symbol `bold' or the string "bold".
> 
> Then I think it should be left undocumented.  That the command takes a
> string sounds like an historical artifact and should not be 
> encouraged.
> 
> I'm closing this report.

What?  Why are you arbitrarily deciding that?  Why not assume that allowing a
string is a good thing, a purposeful design decision?  What makes you conclude
that this is not something to be encouraged?

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.

Recently some code has been changed to name such parameters BLAH-OR-NAME instead
of BLAH.  An example is the bookmark.el code.  (I personally think that's a
mistake - the doc string still needs to say that BLAH-OR-NAME can be a BLAH or
its name.)

But the point here is that allowing FACE to be a string is a *feature*, not a
"historical artifact".  There is no reason to lose this feature, and no reason
it should not be documented.

You should not be designing on the fly that way.  This is a doc bug.  The doc
should mention that FACE can be a face or its name.  Nothing new about this.