GNU bug report logs - #10754
define-minor-mode and doc of derived mode

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: John Shahid <jvshahid <at> gmail.com>
Cc: npostavs <at> gmail.com, 10754 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: bug#10754: define-minor-mode and doc of derived mode
Date: Sat, 30 Jun 2018 10:55:30 +0300

> From: John Shahid <jvshahid <at> gmail.com>
> Date: Fri, 29 Jun 2018 15:48:42 +0000
> Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 10754 <at> debbugs.gnu.org

I have a few minor nits:

> From: John Shahid <jvshahid <at> gmail.com>
> Date: Tue, 5 Jun 2018 19:56:12 -0400
> Subject: [PATCH] optionally include argument description in minor mode DOC
> 
> * easy-mmode.el (define-minor-mode): Add a parapgraph to the mode's
>   docstring documenting the mode ARG usage if the supplied docstring
>   didn't contain the word "ARG".

Please mention the bug number in the log message.

> removed argument documetation from all minor modes.
                   ^^^^^^^^^^^^
Typo.  Also, this should be a full sentence, starting with a capital
letter.

> +(defconst easy-mmode-arg-docstring
> +  "
> +
> +If called interactively, enable %s if ARG is positive, and
> +disable it otherwise.  If called from Lisp, enable the mode if
> +ARG is omitted or nil, and toggle it if ARG is `toggle'. Disable
> +the mode otherwise")

I prefer this text (which also fixes a problem with only one space
between sentences):

  If called interactively, enable %s if ARG is positive, and
  disable it if ARG is zero or negative.  If called from Lisp,
  also enable the mode if ARG is omitted or nil, and toggle it
  if ARG is `toggle'; disable the mode otherwise.

> -documenting what its argument does.
> +documenting what its argument does. If the word \"ARG\" does not
                                      ^
Two spaces between sentences, please.

Thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.