bug#7086: `booleanp' return value is multi-valued list

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 22 Sep 2010 17:58:12 -0400
> From: MON KEY <monkey@sandpframing.com>
> Cc: 
> 
> "Return non-`nil' if OBJECT is one of the two canonical boolean
>  values: `t' or `nil'."
> 
> It should be documented both in the manual and the docstring of `booleanp' that
> its return value is a list.

The precise form of the return value is an implementation detail.
Such details need not be documented.

Are there any _real-life_ use cases where this matter?

> Additionaly, given the nature of this function and the puposes it
> might serve, it
> should be documented _why_ the return value is a list.

Implementation details don't need to be documented, unless they really
matter to Lisp programs which use these APIs.

> Frustratingly, while the manual waxes on about the readers interpretation of
> fundamental identity equivalence w/re `nil' and `()' and their self evaluating
> specialness it has frightening little to offer w/re how one should reflect on
> these things values within lisp programs.

The manual is not a guide to reflections.  Please explain what is
missing, exactly.

> Indeed, while I can appreciate why (booleanp nil) returns a two element list
> I'm unable to reason a rationale for why (booleanp t) doesn't?

Again, why is it important?

> Also, there is this goofiness:
> 
> (defun tt--bool-w/opt (&optional x)
>   (booleanp x))
> 
> (tt--bool-w/opt nil) ;=> (nil t)
> (tt--bool-w/opt t)   ;=> (t)
> (tt--bool-w/opt)     ;=> (nil t)

See (info "(elisp)Argument List") for an instant enlightening: omitted
optional arguments default to nil.

> (defun tt--bool (x)
>   (booleanp x))
> 
> (tt--bool nil)   ;=> (nil t)
> (tt--bool t)     ;=> (t)
> (tt--bool 'nil)  ;=> (nil t)
> (booleanp '())   ;=> (nil t)
> (booleanp ())    ;=> (nil t)
> 
> (tt--bool)
> ;=> Debugger entered--Lisp error:
> ; (wrong-number-of-arguments (lambda (x) (booleanp x)) 0)

Exactly!  See the above node in the manual.

But this has nothing to do with booleanp.

> Emacs lets me define the function but then accuses me of somthing I didn't even
> (appear) to do, i.e. set the constant nil.

Emacs gives you enough rope to hang yourself; don't do that, unless
you mean it.