RE: Predicate for true lists

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

> > We should document the intended behavior, including
> > the error behavior.
> 
> Documenting every function's behavior completely, in that function's doc string or manual section, would waste not only our time, but also time spent by users reading the documentation. Nobody does that, for any nontrivial GNU program I'm aware of. Common sense should prevail, and "document every bit of behavior" absolutism would cause more trouble than it'd cure. Thank goodness we don't do that, and have never done that.

Strawman.  I never said that every function's behavior needs
to be documented completely.  Nor is the text you quoted,
"document every bit of behavior" something I said - it's
just an invention on your part.

That strawman distracts from your argument that not
documenting behavior can protect future changes from being
backward incompatible.  And it distracts from my argument
against that (misguided) argument.

First, I specifically distinguished between design (intended
behavior) and implementation (actual behavior, with bugs).
It's not at all about documenting "every bit of behavior".

And yes, this, like all documentation decisions, is always a
judgment call, and yes, such judgment calls for common sense.

The question here is whether (1) documenting error-handling
behavior in this case is useful to users and (2) whether not
documenting it somehow insulates future changes from being
backward-incompatible.

My point was that not mentioning error-handling behavior
does _not_ make a future change less backward-incompatible.
We should own the current design and, yes, document it for
users.  And as Eli mentioned, if and when the design changes
we can update the documentation accordingly.

That's part (2) of the overall question - the only part I
actually addressed, as a reply to your ("absolutist"?)
statement to the contrary.

And that part (2) applies generally: No documentation
omission or spin can protect against backward compatibility.

It's a mistake to think or pretend that you're not breaking
backward compatibility just because the behavior you change
was never documented.  Compatibility is about behavior, not
just its description.

As for part (1), which I did not speak to, there is no
hard-and-fast rule.  Speaking to it now: I think it probably
is useful in this case (for `*').

But that's just one opinion, and given good counter-arguments
I might change it.  I don't feel strongly about it - I don't
much care about this particular case.  I posted my reply only
because of the wide-ranging, misleading argument you made
about doc silence protecting future changes - IOW, part (2).

Generally speaking, just because makers of non-free software
sometimes try to hide aspects of a design from users, that's
no reason why free software should do the same.  We have
nothing to hide.

That does not provide an imperative to pedantically "document
every bit of behavior" - no connection.  What it does is
remove any special incentive (commercial, "intellectual
property" related, etc.) to self-censor or otherwise not give
users info that could help them.

That we don't have a need to hide info does not imply that
we need to bore or confuse users with a wall of unhelpful
details.

Whether this or that bit of info actually helps users, and
how much, is a judgment call, on a case-by-case basis.  There
is no imperative to pedantically document everything (about
design or implementation) that derives from the argument I
made, nor does my own opinion in this or that case produce
such an imperative.

---

It's probably worth being clear about another aspect of this.
It's quite possible to, by _design_, intend that some part
of the currently implemented behavior is "undefined".  In
that case, yes, there is no explicit commitment to users
about that particular bit of behavior.

My own opinion is that it can often be a good idea in such
a case to explicitly call out that that bit is undefined.
That serves as an explicit warning, of sorts, that the
behavior might well change in the future.  (Any behavior
might change in the future; this points out that this
particular behavior is undefined.)

In the case at hand, is the error-handling behavior of
arguments part of the design or just something to be
considered undefined - implemented but not really
intended?  I think, from the discussion, that it's part
of the design, but perhaps not?

But even in the case where something is considered
undefined, and even with an explicit warning about it,
a backward-incompatible change is just that - it doesn't
become less backward-incompatible just because we excluded
that part of the behavior from the design.

Backward incompatibility is about actual behavior, always.
"The design didn't really change" is not a welcome answer
to "You broke my code".  It's pretty much a cop-out.

This is not a legalistic point of view.  It's a view
centered on users.  It's not about whether the software
producer can be held liable or is better able to resist
a lawsuit.  It's about what is most useful for Emacs and
its users.