GNU bug report logs -
#26301
24.5; `define-derived-mode': different signatures for doc string & manual
Previous Next
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Wed, 29 Mar 2017 15:05:01 UTC
Severity: wishlist
Tags: fixed
Found in version 24.5
Fixed in version 27.1
Done: Lars Ingebrigtsen <larsi <at> gnus.org>
Bug is archived. No further changes may be made.
Full log
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
The signature is ultimately the same but it is documented differently.
It would be better to use the same signature spec for both, unless
there is a good reason not to.
In the manual it is declared as being:
define-derived-mode variant parent name docstring keyword-args… body…
In the doc string it is declared as being:
(define-derived-mode CHILD PARENT NAME &optional DOCSTRING &rest BODY)
No KEYWORD-ARGS. They are included in BODY, so the specifications of
BODY differ between the two.
The doc string says: "BODY can start with a bunch of keyword arguments."
What's a "bunch" here? Any number? Not very clear.
For both doc string and manual: Can any of the keyword args be repeated?
Can you, for example, use :group more than once, to specify belonging to
multiple groups? If not, and if a keyword arg is present more than once,
which one gets used? Or is an error raised? The treatment of keyword
args is not well specified.
In the doc string, this expression is not good: "On a more complicated
level". Unclear, misleading, unhelpful.
(On the plus sign, this doc string xrefs the node in the manual.)
The manual also says this:
"Only the (still experimental and unadvertised) command ‘customize-mode’
currently uses this [the customization group]."
The "still experimental and unadvertised" part is inappropriate, IMHO.
And by including it we've just advertised it! It is unclear what this
statement is trying to convey to users, and why.
In GNU Emacs 24.5.1 (i686-pc-mingw32)
of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --prefix=3D/c/usr --host=3Di686-pc-mingw32'
This bug report was last modified 5 years and 321 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.