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

[Juanma Barranquero]

On Sat, Aug 17, 2013 at 6:14 PM, Drew Adams <drew.adams@oracle.com> wrote:

> 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.

Sorry, I still disagree. The general rule is always that if nothing is
said, nothing can be assumed (or, alternatively, assume at your own
peril). Many functions *do* declare their return value, but that is
generally because the return value is potentially useful. More power
to them (and us). For the rest, adding a note saying that the return
value is undefined is nice, but in many cases unnecessary and verbose
IMO. And I don't think laziness is involved, BTW.

>   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:

I don't see how the coder could fail to notice that there's a good
reason not to use the return value of some specific function, if that
return value is undocumented.

This is not theoretical. Sometimes I've used the return value of a
function without looking at its docstring. When afterwards I've
wondered whether I was doing the right thing, a simple look and the
realization that it wasn't, in fact, documented, was enough to go "oh,
bummer" and fix my code. "The return value of this function is
undefined" would've added nothing of value, except in functions with
very large or complex docstrings. And, in this cases, the docstring
author *can* add the notice; it's not forbidden.

Summarizing: I agree it can be OK to add the notice. I don't agree
there's some kind of obligation to document that it is undefined.

   J