GNU bug report logs - #26301
24.5; `define-derived-mode': different signatures for doc string & manual

Previous Next

Full log

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 26301 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#26301: 24.5;
 `define-derived-mode': different signatures for doc string & manual
Date: Fri, 26 Jul 2019 10:54:31 -0400

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Drew Adams <drew.adams <at> oracle.com> writes:
>
>> 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.
>
> I guess the manual here try to describe the conceptual semantics (i.e.,
> that if you put keywords there, they'll be interpreted as such), while
> the doc string doesn't lie about what goes where.  Because the calling
> convention is automatically generated there, which makes pretending a
> bit more difficult.

Docstrings can override the automatically generated signature by using

(fn ...)

So maybe we should do that here?

Previous Next

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