GNU bug report logs - #15116
24.3.50; doc of `set-match-data'

Previous Next

Full log

View this message in rfc822 format

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15116 <at> debbugs.gnu.org
Subject: bug#15116: 24.3.50; doc of `set-match-data'
Date: Sun, 18 Aug 2013 04:06:36 +0200

On Sat, Aug 17, 2013 at 8:37 PM, Drew Adams <drew.adams <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.