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

From: Drew Adams <[email-masked]>
Date: Fri, 23 May 2014 12:35:53 -0700 (PDT)

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