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

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

[Drew Adams]

Both the doc string and (elisp) Entire Match Data should say what the
return value is.

The doc for every Emacs function should say what the return value is.

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-08-07 on ODIEONE
Bzr revision: 113750 lekktu@gmail.com-20130808011911-0jzpc9xuncegg6x9
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 CFLAGS=-O0 -g3 LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

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

[Juanma Barranquero]

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

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

   J

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

[Drew Adams]

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

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

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

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

[Juanma Barranquero]

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

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

Sorry, I again disagree. I don't think that not documenting a return
value, when there's is a clear default ("if not documented, nothing
can be assumed") is being unhelpful. For every documentation there are
things that must be clearly stated, and others that can be left unsaid
because they are part of the landscape. Someone who pretends to use an
Emacs function already has in their mental landscape the idea that:
not documented, nothing can be assumed.

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

Not stating every repetitive nuance is not "being wrong".

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

No, I don't think so.

> We should not be thinking only like litigation defense lawyers here
> ("We never promised you...").

That's a straw man. No one here is thinking that.

>  We should be thinking of users and how
> best to help them.  They are, after all, the raison d'etre du produit.

Well, yes, but no all of us define "help them" in the same way that you do.

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

Again, please don't put words in my mouth that I didn't say, or ideas
in my words that I didn't express and don't really believe. No one is
talking about "what the user can rightfully [...] claim".

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

How difficult is for the user to understand that, not mentioned => do
not assume anything? Should we state in *every* docstring *every*
assumption that can be possibly misinterpreted, however common and
clear it is? At which point do we stop and just trust the user to be
smart?

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

That's not an argument, that's just *your* opinion.

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

Nothing to "think again". Yes, I don't see how the coder can fail to
notice that the function's return is undocumented and so there's a
good reason not to use its return value. We can dance all night and
still nothing will change.

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

Nonsense. That I defend not having to document a *non-useful* return
value does not imply that I defend *not saying* in the docstring that
the function is called for side effects only, or not clearly
explaining what the function *does*. Returning a value, it *doesn't*
do, in any meaningful way. Let's concentrate in documenting what the
function does, because what it doesn't do... that could be very long
indeed.

> (b) users should not
> assume these functions are non-destructive (or destructive), since the
> doc says nothing about this.

Your connection between "not documenting its return value" and "not
explaining that they have side effects (destructive or not)" is
spurious and I don't accept it.

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

I'd like you ask you to please skip all that "promise" rhetoric. It's
false, it's insulting, and does not help in this discussion.

(Also, as you know very well because your help was invaluable, about
60% of frameset.el non-empty lines are comments or docstrings; so this
accusation is particularly amusing...)

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

I like how you apparently think that adding stuff to a docstring has
no cost and it's always valuable. Irrelevant things add complexity and
verbosity. The longer a docstring is, the easier is for someone to
skip important bits lost among the verbiage.

> Whether you call it "obligation" or not, we can, and so we should,

Again...

> There is really no reason not to share this info
> with those for whom the product is developed.  It just helps.

Yeah, it is quite clear that you think so.

   J

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

[Glenn Morris]

Drew Adams wrote:

> The doc for every Emacs function should say what the return value is.

Awesome, so now we can expect 100s of reports about this, complete with
little lectures when we disagree.

As Juanma said; no, they shouldn't.

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

[Drew Adams]

> Awesome, so now we can expect 100s of reports about this, complete
> with little lectures when we disagree.

Too bad.  It's not about minimizing development.  It's about helping
users and specifying clearly (yes, for developers too) just what the
language is.

If Common Lisp can do it (and has done it for 30 years) then the
self-vaunted "self-documenting" editor can do it too.

It just means thinking also `user' and `spec', not just `code'.
Emacs is a big boy now; he should be able to handle this.