bug#18024: 24.4.50; doc of `y-or-n-p' misses the main functionality: what it returns

bug#18024: 24.4.50; doc of `y-or-n-p' misses the main functionality: what it returns

[Drew Adams]

1. `y-or-n-p' is a *predicate*.  This is missing from the doc string,
because it says nothing about what the function returns if the user
answers `n' instead of `y'.  The doc string *must* tell users that `n'
means return nil.

2. The Elisp manual does not have that failing.  However, to be clear,
both it and the doc string should specify that *whatever* way the user
answers in the affirmative means return `t', and *whatever* s?he answers
in the negative means return `nil'.  Currently the manual specifies the
return value only for `y' and `n'.

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-28 on ODIEONE
Bzr revision: 117431 rgm@gnu.org-20140628015517-eku6hj8mpgcvfnso
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#18024: 24.4.50; doc of `y-or-n-p' misses the main functionality: what it returns

[Glenn Morris]

Oh my goodness!
And I wonder what integerp returns when the argument is not an integer?!
Or floatp when the argument is not a float?!
The list goes on!

Somebody fix this ASAP!
TIA.

bug#18024: 24.4.50; doc of `y-or-n-p' misses the main functionality: what it returns

[Drew Adams]

> what integerp returns when the argument is not an integer?!
> Or floatp when the argument is not a float?!
> The list goes on!  Somebody fix this ASAP!

Good idea, Glenn.  Those doc strings too should speak about t and
nil, rather than just t.  They should start by saying that they
test whether OBJECT is an integer etc., and end by stating what
the return values are.

TIA.

bug#18024: 24.4.50; doc of `y-or-n-p' misses the main functionality: what it returns

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> 1. `y-or-n-p' is a *predicate*.  This is missing from the doc string,
> because it says nothing about what the function returns if the user
> answers `n' instead of `y'.  The doc string *must* tell users that `n'
> means return nil.

I've now changed the doc string to say what the "n" value is.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no