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

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

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

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.

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