bug#17567: 24.4.50; doc string of `define-derived-mode'

[Stefan Kangas]

tags 17567 + fixed
close 17567 28.1
thanks

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

> The doc string erroneously says that parameter NAME is "a string
> which will appear in the status line".
>
> Emacs does not have a "status line".  That term is used nowhere.
>
> What should be said about NAME is that it defines the value of variable
> `mode-name' for mode CHILD.  A user consulting that variable will see
> that its value is used in the mode line etc.

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

> Also, the doc string should state the types of the values of
> keywords :group, :syntax-table, and :abbrev-table.
>
> And it says that the mode runs the hook constructed by function
> `derived-mode-hook-name'.  Constructed how?  What does constructed
> mean here?
>
> And the doc string of `derived-mode-hook-name' is no help here:
> "Construct a mode-hook name based on a MODE name."
>
> The arg is MODE.  What is it?  What data type?  And what is
> its "name"?  What does it mean to construct a hook name?
> And how is that name constructed from the "MODE name"?
>
> And what about the contradiction between the doc string of
> `define-derived-mode' and that of `derived-mode-hook-name'?
> The former says that `d-m-h-name' constructs a _hook_.  The
> latter says that it constructs a hook _name_.
>
> Far clearer for `derived-mode-hook-name' would be to just
> say what it really does:
>
>   Return a symbol whose name is "-hook" appended to the
>   `symbol-name' of MODE.
>
> That also makes it clear that MODE is expected to be a symbol.
>
> (Similarly, for the other `defsubst's in derived.el.)

I have now fixed this on (commit e4c9081d46).  This change will be a
part of the upcoming Emacs 28.1.

Please verify that this fix works for you, but for now I'm closing this
bug report.  If you see anything that is wrong, please reply to this
email (use "Reply to all" in your email client) and we can reopen the
bug report.  You could also just report a new bug.

Thanks again for the bug report!