bug#15116: 24.3.50; doc of `set-match-data'

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

> > The doc for every Emacs function should say what the return value is.
> 
> Hm. I disagree. Many functions are used just by their side effects,

1. "Many" in absolute terms.  Very few in relative terms.  They are
   exceptions to the rule, not the norm.  This is Lisp, not C.

2. Such exceptional functions should be *explicitly documented* as
   such.  See below.  See the Common Lisp spec and doc, as a good
   model to follow.

> and forcing them to declare a return value and keep it forever
> back-compatible is unreasonable, especially when the return value is
> quite arbitrary. You simply shouldn't rely on them returning anything
> sensible.

100% agreed, wrt those few, exceptional functions, *provided* that this
exceptional do-not-rely-on-return-value behavior is explicitly
documented.  Users get what they deserve, *provided* they have been told
explicitly not to count on the return value.  If we do not tell them
that then they deserve better.  They deserve and should expect a
reasonable return value if we do not advise them otherwise.

The (unwritten) rule should *not* be that if the Emacs doc says nothing
about a return value then you should assume that it is undefined (you
cannot rely on it).

The rule should be that the doc for each function either (a) specifies
the return value or (b) tells you that the return value is undefined
(do not rely on it) and the function is used only for its side effects.

In sum: the rule should be explicitness in our doc, not just lazy
omission of such important information.

FWIW, I was more exact in what I said in bug #15117:

  If, for some special (good) reason, code should not rely on the 
  return value of some function then this fact should be stated 
  explicitly in the doc: "This function is used only for its side 
  effects; the return value is undefined."  This is Lisp, not C - 
  return values are the norm, not the exception.

NB. "for some *special* (*good*) reason".