Keywords supported by define-minor-mode

Keywords supported by define-minor-mode

[Eli Zaretskii]

I needed today to understand what exactly this does:

  (define-minor-mode midnight-mode
    "Non-nil means run `midnight-hook' at midnight."
    :global t
    :initialize #'custom-initialize-default
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

I was astonished to find out that this keyword is not documented
anywhere, neither in the doc string of define-minor-mode, nor in the
manual.  The full list of define-minor-mode's keywords that aren't
documented is this:

  :extra-args
  :set
  :initialize
  :type

Could someone please document these, or at least describe them here in
their own words (so that someone else could update the documentation
accordingly)?  We shouldn't leave such important functionality
undocumented for so long.

TIA

Re: Keywords supported by define-minor-mode

[Stefan Monnier]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

> I needed today to understand what exactly this does:
>   (define-minor-mode midnight-mode
>     "Non-nil means run `midnight-hook' at midnight."
>     :global t
>     :initialize #'custom-initialize-default
>     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

> I was astonished to find out that this keyword is not documented
> anywhere, neither in the doc string of define-minor-mode, nor in the
> manual.  The full list of define-minor-mode's keywords that aren't
> documented is this:

>   :extra-args
>   :set
>   :initialize
>   :type

The latter three are covered by this part of the docstring:

    (other keywords are passed to ‘defcustom’ if
    the minor mode is global)


-- Stefan

Re: Keywords supported by define-minor-mode

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Sun, 27 Mar 2016 18:38:38 -0400
> 
> >   :extra-args
> >   :set
> >   :initialize
> >   :type
> 
> The latter three are covered by this part of the docstring:
> 
>     (other keywords are passed to ‘defcustom’ if
>     the minor mode is global)

Yes, but defcustom's documentation is monstrously large, and doesn't
always make sense to someone who just wants to define a minor mode,
easily.

And it still leaves :extra-args.

Re: Keywords supported by define-minor-mode

[Stefan Monnier]

>> >   :extra-args
>> >   :set
>> >   :initialize
>> >   :type
>> 
>> The latter three are covered by this part of the docstring:
>> 
>> (other keywords are passed to ‘defcustom’ if
>> the minor mode is global)

> Yes, but defcustom's documentation is monstrously large, and doesn't
> always make sense to someone who just wants to define a minor mode,
> easily.

Might be true.  But :set, :initialize, and :type are more important for
defcustom than for define-minor-mode, so it'd be more beneficial to
address the issue on defcustom's side than on define-minor-mode side.

> And it still leaves :extra-args.

Yes.


        Stefan

Re: Keywords supported by define-minor-mode

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: emacs-devel@gnu.org
> Date: Mon, 28 Mar 2016 11:50:08 -0400
> 
> >> (other keywords are passed to ‘defcustom’ if
> >> the minor mode is global)
> 
> > Yes, but defcustom's documentation is monstrously large, and doesn't
> > always make sense to someone who just wants to define a minor mode,
> > easily.
> 
> Might be true.  But :set, :initialize, and :type are more important for
> defcustom than for define-minor-mode, so it'd be more beneficial to
> address the issue on defcustom's side than on define-minor-mode side.

All I'm saying is that the doc string of define-minor-mode and the
manual text about it might be more user-friendly if they described
those keywords right there, from the POV of the mode author.