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

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

[Drew Adams]

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'

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

[Lars Ingebrigtsen]

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.

I don't think describing it both ways is very confusing.

> The doc string says: "BODY can start with a bunch of keyword arguments."
> What's a "bunch" here?  Any number?  Not very clear.

I've now rewritten to avoid the amusing word.

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

I don't think any of those questions are reasonable, so saying something
about that would be confusing.

> In the doc string, this expression is not good: "On a more complicated
> level".  Unclear, misleading, unhelpful.

"As a more complex example" is perhaps better.

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

I can't find the string "experimental" in that node in the manual, so I
guess this has been fixed.

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

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

[Drew Adams]

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

"The doc string doesn't lie."  Is that the best we
can say for it?  Why gratuitously introduce a mismatch
between the two?  That just makes things harder for
users, no?

I don't know what you're saying by your last sentence,
in particular this: " which makes pretending a bit more
difficult."  No idea what pretending you mean.

What's the reason we wouldn't want KEYWORD-ARGS
described in the doc string?
 
> I don't think describing it both ways is very confusing.

Why should it be confusing at all?  Is plain confusing
OK but very confusing not OK?  It might be OK if there
were a good reason for it, but I haven't seen that yet.

> > The treatment of keyword args is not well specified.
> 
> I don't think any of those questions are reasonable,

Why?  What's unreasonable about wanting to know
whether you can specify multiple :group entries,
as you can do with defcustom, for instance?

We specifically provide such info for `defcustom'
(elisp) `Common Keywords', under `:group':

  If you use this keyword more than once, you can put
  a single item into more than one group.

`define-minor-mode' generates defcustom forms.  Its
doc should at least say that KEYWORD-ARGS can be
any list of keyword entries acceptable to defcustom,
and then point to the defcustom doc (where we say
that you can use multiple :group's to add an option
to multiple groups.

> so saying something about that would be confusing.

Do you think our saying it for defcustom is confusing
also?  Why should it be confusing here?  That's exactly
what KEYWORD-ARGS specifies: defcustom keyword entries.

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

[Noam Postavsky]

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?

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

[Lars Ingebrigtsen]

Noam Postavsky <npostavs@gmail.com> writes:

> Docstrings can override the automatically generated signature by using
>
> (fn ...)
>
> So maybe we should do that here?

Hm...  didn't think about that.  I guess that makes sense?  We'd say

(fn ... &rest KEYWORDS &body body)

or something?  (Slightly Common Lispish.)

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

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

[Drew Adams]

> > Docstrings can override the automatically generated signature by
> using
> >
> > (fn ...)
> >
> > So maybe we should do that here?
> 
> Hm...  didn't think about that.  I guess that makes sense?  We'd say
> 
> (fn ... &rest KEYWORDS &body body)
> 
> or something?  (Slightly Common Lispish.)

I'm no expert on how we would write it.
But in Common Lisp you cannot have both &rest
and &body at the same level, I believe.

Maybe this?

(fn CHILD PARENT NAME &optional DOCSTRING KEYWORDS &rest BODY)

And let the doc string describe KEYWORDS properly,
to make clear that it's any number of keyword
entries (keyword followed by its value).

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

[Drew Adams]

> Docstrings can override the automatically generated signature by using
> (fn ...)
> So maybe we should do that here?

Exactly.  I should have thought to suggest that myself.
Please do.

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

[Lars Ingebrigtsen]

Noam Postavsky <npostavs@gmail.com> writes:

> Docstrings can override the automatically generated signature by using
>
> (fn ...)
>
> So maybe we should do that here?

I grepped a bit and had a look at what a few other functions that have
the same general issue (i.e., that the BODY argument may be prepended
with stuff that's "logically" a different argument):

(defmacro cl-defgeneric (name args &rest options-and-methods)
\(fn NAME ARGS [DOC-STRING] [OPTIONS-AND-METHODS...] &rest DEFAULT-BODY)

(defmacro cl-defmethod (name args &rest body)
\(fn NAME [QUALIFIER] ARGS &rest [DOCSTRING] BODY)"

(defmacro pcase-defmacro (name args &rest body)
\(fn NAME ARGS [DOC] &rest BODY...)

So if we model ourself after cl-defgeneric here, that'd be:

(defmacro define-derived-mode (child parent name &optional docstring &rest body)
\(fn CHILD PARENT NAME [DOCSTRING] [KEYWORDS...] &rest BODY)

So I've now done this and adjusted the rest of the doc string
accordingly.

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

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

[Drew Adams]

> \(fn CHILD PARENT NAME [DOCSTRING] [KEYWORDS...] &rest BODY)
> 
> So I've now done this and adjusted the rest of the doc string
> accordingly.

Sounds good.  That's what I suggested, but with the
addition of the `...' (good).

However, in that case, KEYWORDS is the _wrong_ name.

It is not _keywords_, which is presumably a _list_
of keywords (or more exactly, keyword key-value
pairs), that is repeated.  What is optional is not
a list of lists.  What is optional is a list of
keywords (or more exactly...).

The name should be KEYWORD or KEYWORD-ENTRY or
KEYWORD-PAIR or some such.  It should not be
KEYWORDS.

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

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> > \(fn CHILD PARENT NAME [DOCSTRING] [KEYWORDS...] &rest BODY)
> >
> > So I've now done this and adjusted the rest of the doc string
> > accordingly.
>
> Sounds good.  That's what I suggested, but with the
> addition of the `...' (good).
>
> However, in that case, KEYWORDS is the _wrong_ name.

In a similar case, `define-globalized-minor-mode' uses the name KEYS
(it's the name of the &rest arg though).

> The name should be KEYWORD or KEYWORD-ENTRY or KEYWORD-PAIR or some
> such.

I all find that not better.  KEYWORD fails to say that values are
included.  KEYWORD-ENTRY and KEYWORD-PAIR are confising, they make it
look like you would have to specify conses or two element lists.

I would prefer something like [KEYWORD VALUE ...], though I guess that
would then confuse eldoc.

Michael.

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

[Drew Adams]

> > However, in that case, KEYWORDS is the _wrong_ name.
> 
> In a similar case, `define-globalized-minor-mode' uses the name KEYS
> (it's the name of the &rest arg though).

If each of the args in the &rest list is a KEY
then that's fine.

> > The name should be KEYWORD or KEYWORD-ENTRY or KEYWORD-PAIR or some
> > such.
> 
> I all find that not better.  KEYWORD fails to say that values are
> included.  KEYWORD-ENTRY and KEYWORD-PAIR are confising, they make it
> look like you would have to specify conses or two element lists.
> 
> I would prefer something like [KEYWORD VALUE ...], though I guess that
> would then confuse eldoc.

That's incorrect, I think, because it indicates
that VALUE is what is possibly repeated.  If the
convention doesn't actually specify that (I'm not
sure) that's at least what someone might suppose.

Dunno whether our convention allows [KEYWORD VALUE]...
(i.e., with the ... after the optional indication).

Otherwise, I'd suggest a name such as KEYWORD+VALUE:

 [KEYWORD+VALUE...]

(If this were not something added automatically by
handling (fn ...) then a single name (e.g. FOOBAR)
could be broken down in the doc string, saying that
FOOBAR is a keyword followed by its value.)

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

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> > > However, in that case, KEYWORDS is the _wrong_ name.
> >
> > In a similar case, `define-globalized-minor-mode' uses the name KEYS
> > (it's the name of the &rest arg though).
>
> If each of the args in the &rest list is a KEY then that's fine.

No, that's not the case.

> Dunno whether our convention allows [KEYWORD VALUE]...
> (i.e., with the ... after the optional indication).

Yes, or even [[KEYWORD VALUE]...]?

I don't know if we have an official convention at all.  In this case
here, since &rest is following this specification, I think eldoc will be
confused in any case since it can't distinguish between keyword-value
pairs and the following &rest BODY.

Michael.