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

[Noam Postavsky <npostavs@gmail.com>]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Drew Adams <drew.adams@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?