Re: Making DOC argument of define-minor-mode optional

[Philipp Stephani <p.stephani2@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1994 bytes --]

Philipp Stephani <p.stephani2@gmail.com> schrieb am So., 27. Nov. 2016 um
22:13 Uhr:

> Drew Adams <drew.adams@oracle.com> schrieb am Mi., 23. Nov. 2016 um
> 17:35 Uhr:
>
> > >> the docstring created by define-minor-mode with nil DOC is useful
> > >> and often better than what users write.
> > >> Should DOC therefore be optional?
> > >
> > > Not sure we would like to educate Lisp programmers to stop
> > > thinking about good doc strings.
> >
> > I agree.
>
> Me too.  And definers of user-facing things, such as
> defcustom and defface, do require DOC.  Other definers,
> such as defconst and defvar, do not require it.
>
> On the other hand, OP raises a real issue, I think.
>
> I'd be in favor of (somehow) automatically having the
> definer-provided DOC be augmented by a link that shows
> the generic `define-minor-mode' doc, or similar.
>
> IOW:
>
> 1. Definers should need to provide a DOC string (even if
>    they can fake it with "", which is not encouraged).
>
> 2. Users of the mode should have access to the generic
>    information also.  It should be sufficient that the
>    DOC in the definition provides mode-specific information.
>    It should not need to tell users general things about
>    using a minor mode.
>
>
> That sounds like a good approach.
>

Do you have a good idea how to design the interface for this? I was
thinking about something like this: Create a new help type, "mode",
analogous to "variable" and "function". The documentation for the mode
would be different from the toggle command and the mode variable, which
would get a generic docstring. C-h o and C-h m would show the mode
docstring instead of the toggle command docstring. The mode docstring would
contain only a description of the mode itself, not the toggle command.
The primary downside is that many mode docstrings are written to be
applicable to the toggle command. Maybe `define-minor-mode' could grow a
:doc keyword argument for the mode docstring to preserve backward
compatibility.

[-- Attachment #2: Type: text/html, Size: 3503 bytes --]