Subject: bug#10724: 24.0.93; doc of `typecase'

From: "Drew Adams" <[email-masked]>
Date: Sat, 4 Feb 2012 10:00:59 -0800

The doc string does not meet Emacs standards.  The arguments are not
described.
 
Nothing is said about what EXPR, TYPE or BODY can be.  BODY is
excusable; the others are not.

We must state that EXPR is any Emacs-Lisp sexp (if that is the case).
 
And we must state that TYPE is an emacs-lisp type name, as a symbol (if
that is the case).  But that's not sufficient, since there is not just a
single list of such type names.
 
There are at least the following that a reader might understand for
TYPE when reading this doc:
 
1. the simple-type names for Customize
2. type predicates
3. programming types ((elisp) Programming Types)
4. editing types ((elisp) Editing Types)
 
For the last two (#3 and #4), which are probably what is meant here,
what symbols (is TYPE a symbol?) are recognized for those types by
`typecase'?
 
You cannot program using `typecase' without knowing this stuff.  And
though Emacs Lisp's `typecase' presumably corresponds somewhat to Common
Lisp's, it is not at all obvious just what values of TYPE are supported
by Emacs Lisp.

In GNU Emacs 24.0.93.1 (i386-mingw-nt5.1.2600)
 of 2012-01-29 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include --ldflags
 -LD:/devel/emacs/libs/gnutls-3.0.9/lib'