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

[Drew Adams]

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

A user's OWN rule has to be, yes, that if the doc says nothing then
all bets are off.  That is more or less of the same value as "caveat
emptor" and "Don't talk to strangers": advice that says that you
cannot depend on kindness or honesty etc.

But that is not an excuse for the doc to help users less than it can.
Just because a user has to be careful and not assume anything about
what is not said explicitly is not a reason to dispense with helping
users.  It is not a reason to not be explicit.

The wise user even applies the same rule to what IS said.  It might
just be incorrect, so don't trust it completely.  That is not an
excuse for the doc to be wrong, is it?

You are confusing, I think, what a user can assume with what we should
tell users, to help them use the product.

We should not be thinking only like litigation defense lawyers here
("We never promised you...").  We should be thinking of users and how
best to help them.  They are, after all, the raison d'etre du produit.

You seem to want to put the burden on users, not Emacs.  That's
backwards.  Forget about what users can rightfully assume or claim,
or what they might complain about.  Think about what helps them.

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

The burden should be on the doc, not the user.  If the language
designers intend for a particular function to be used only for side
effects then we can and should help users by letting them know that
that is the case.  How much effort does that take?  How verbose does
it make the doc to add that for the few functions to which it applies?

Anything less than that is discourteous, unless it is an oversight.
And that is the case whether the reason is laziness or something else.

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

You don't see how someone can fail to notice the reason a function
is to be used only for side effects?  Notice the reason?  Think again.

Do you take the same attitude wrt functions that modify list structure?
Scheme even goes to the trouble of giving them names that end in `!',
to make explicit (even obvious!) that they are "destructive".

Would you take the point of view that their doc need say nothing about
this part of their behavior, under the rationale that (a) users should
not fail to figure this out on their own, and (b) users should not
assume these functions are non-destructive (or destructive), since the
doc says nothing about this.

Why not just remove the doc altogether?  That way we promise nothing,
the user is careful and figures things out alone, we save lots of
development effort, and verbosity goes to zero!  Hurrah.

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

If it can be OK in your opinion, then we can make the effort to help
users by adding it.  It's about doing the right thing.  Does that mean
"obligation" to you?  Just because something is not obligatory and
enforced somehow, that does not mean that it should not be done.

Whether you call it "obligation" or not, we can, and so we should,
help users by being explicit about what side effects occur and what
value is returned.  There is really no reason not to share this info
with those for whom the product is developed.  It just helps.

Emacs should take a tip from its big brother, Common Lisp: write it
down, for all to see.  (You might be surprised how much that will
help even Emacs developers.)