GNU bug report logs - #10724
24.0.93; doc of `typecase'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 10724 in the body.
You can then email your comments to 10724 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.93; doc of `typecase'
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'
 

Message #8 received at 10724 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <10724 <at> debbugs.gnu.org>
Subject: RE: bug#10724: 24.0.93; doc of `typecase'
Date: Sun, 16 Sep 2012 17:16:26 -0700

ping

Message #11 received at 10724 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 10724 <at> debbugs.gnu.org
Subject: Re: bug#10724: 24.0.93; doc of `typecase'
Date: Sat, 08 Feb 2014 21:14:48 -0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> 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.

This seems to be another report about not putting the entirety of the
Common Lisp standard into the doc strings of the cl-* functions.
Closing.

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

Previous Next

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