From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Philipp Stephani Newsgroups: gmane.emacs.bugs Subject: bug#24706: 26.0.50; Minor mode functions should do strict argument type checking Date: Sun, 16 Oct 2016 18:13:01 +0000 Message-ID: References: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=001a114699d08ce224053eff699f X-Trace: blaine.gmane.org 1476641660 7335 195.159.176.226 (16 Oct 2016 18:14:20 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 16 Oct 2016 18:14:20 +0000 (UTC) To: Drew Adams , 24706@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Oct 16 20:14:16 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bvpwo-0000Zg-EZ for geb-bug-gnu-emacs@m.gmane.org; Sun, 16 Oct 2016 20:14:10 +0200 Original-Received: from localhost ([::1]:57392 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bvpwq-0000F8-F2 for geb-bug-gnu-emacs@m.gmane.org; Sun, 16 Oct 2016 14:14:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38366) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bvpwj-0000El-LJ for bug-gnu-emacs@gnu.org; Sun, 16 Oct 2016 14:14:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bvpwg-0004ZJ-Dr for bug-gnu-emacs@gnu.org; Sun, 16 Oct 2016 14:14:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:57452) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1bvpwg-0004Yw-9O for bug-gnu-emacs@gnu.org; Sun, 16 Oct 2016 14:14:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1bvpwf-0007UJ-RN for bug-gnu-emacs@gnu.org; Sun, 16 Oct 2016 14:14:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Philipp Stephani Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 16 Oct 2016 18:14:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 24706 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 24706-submit@debbugs.gnu.org id=B24706.147664160028718 (code B ref 24706); Sun, 16 Oct 2016 18:14:01 +0000 Original-Received: (at 24706) by debbugs.gnu.org; 16 Oct 2016 18:13:20 +0000 Original-Received: from localhost ([127.0.0.1]:35405 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bvpvz-0007T8-Mi for submit@debbugs.gnu.org; Sun, 16 Oct 2016 14:13:19 -0400 Original-Received: from mail-lf0-f49.google.com ([209.85.215.49]:36197) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bvpvx-0007St-Tz for 24706@debbugs.gnu.org; Sun, 16 Oct 2016 14:13:18 -0400 Original-Received: by mail-lf0-f49.google.com with SMTP id b75so244842538lfg.3 for <24706@debbugs.gnu.org>; Sun, 16 Oct 2016 11:13:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:references:in-reply-to:from:date:message-id:subject:to; bh=Z660pfWTBfbJ2WTS+cBLTN8fWydm12824lyeMvlNm+s=; b=UdKAVayGZS6A3mVWaG6tG0PZc341VMpLk76jRvA9aEYqi2tp10wBpF+G35p4NPIHp4 E/rI5C97oOVDtnkIqW0AZuiUXn7VaRdSJbwjKyZQCTLX/Y7ObI83Tx6peZGcQFMhBhMj ll/WVloEbMdJUGT+XLChMs9bknPlZvMYkrW40eO+9DS8wmna/SJsT4YTkOchaiutaaX4 YjgKD0wy3xvN4lT32DcTi+Vg2V6YuBwSB+VKfd7IqnpOFcGwcSLCC90tzbTX0iFFPt7s 1AECbONs3PxycU54rggD/NvYdRq76QBuNI8L/0btraQs/DgZZ7dIUG0H2Voq6NxW0Z1v AwFA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to; bh=Z660pfWTBfbJ2WTS+cBLTN8fWydm12824lyeMvlNm+s=; b=aMA7goKDwMN5AjKgWq9igf1FPKhHC/hOVo/NGqs+5U3A2d4fwrWsIeuOyv/IbV0q2e W2cHgcEolM3nKQiuJoqaNOTsDOgYW/czO0VQ9U7g57slQm9vv/smINILFkK7RIoC8LoE k4ozjN76YLXINawdCrF6IuV0tj3ifOYBpObN77UDV/RHNQFbEckzFIAnAHSSG2edYW7A NLeF0B32VO9WRV/EtKw3EB5a8v9YKDNKqt7cc4uW3NSziBqIwAZgkhsyS+4ldIBmb5d0 GQs0EfQv/9nceKQtTN5mf/yvQqNn5ApUmKu+E9wkXTUMvoMrqJ1IGjGj0C7v6nybK3gH yJGw== X-Gm-Message-State: AA6/9RkQp2xbfhEma/SwZwp/crQLppm2B/rzOxq8jezP0RCnEY1TWpQ0N1NqOwR+EDX7KuroSnleeOeNoEVe/w== X-Received: by 10.28.210.1 with SMTP id j1mr6223420wmg.86.1476641591974; Sun, 16 Oct 2016 11:13:11 -0700 (PDT) In-Reply-To: X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:124562 Archived-At: --001a114699d08ce224053eff699f Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Drew Adams schrieb am So., 16. Okt. 2016 um 18:12 Uhr: > > (define-minor-mode foo-mode nil) > > its docstring will be > > > > "Toggle Foo mode on or off. > > With a prefix argument ARG, enable Foo mode 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 =E2=80=98tog= gle=E2=80=99." > > > > This appears to indicate that (foo-mode 'banana) > > should disable foo-mode, but it enables it. > > No, it does not suggest that. But to be clearer, it should > probably explicitly address the non-nil and non-`toggle' case, > like so: > > If called from Lisp, enable the mode if ARG is omitted or > nil, toggle it if ARG is =E2=80=98toggle=E2=80=99, and disable it if AR= G is > any other non-nil value. > > (And place the Lisp description in a separate paragraph > from the interactive description.) > > > I think minor modes should simply not allow anything but > > integers and 'toggle for ARG, avoiding this confusion. > > Why? There is no confusion possible, once the doc string > explicitly speaks about all possible argument values. > > Why would you change the behavior, instead of just clarifying > the doc? > I generally prefer the behavior to be as strict as possible. Consider (foo-mode 'disable) If you read such code, do you assume that this enables foo-mode? However, in this case I guess it's too late, and fixing the documentation is indeed more appropriate. BTW, the Elisp manual has the same issue: The mode command should accept one optional argument. If called interactively with no prefix argument, it should toggle the mode (i.e., enable if it is disabled, and disable if it is enabled). If called interactively with a prefix argument, it should enable the mode if the argument is positive and disable it otherwise. If the mode command is called from Lisp (i.e., non-interactively), it should enable the mode if the argument is omitted or =E2=80=98nil= =E2=80=99; it should toggle the mode if the argument is the symbol =E2=80=98toggle= =E2=80=99; otherwise it should treat the argument in the same way as for an interactive call with a numeric prefix argument, as described above. Probably this should be reworded so that the Lisp case doesn't refer to the interactive case at all. Making the documentation obvious is more important than avoiding repetition. --001a114699d08ce224053eff699f Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable


Drew A= dams <drew.adams@oracle.com= > schrieb am So., 16. Okt. 2016 um 18:12=C2=A0Uhr:
> (define-minor-mode foo-mode nil)
> its docstring will be
>
> "Toggle Foo mode on or off.
> With a prefix argument ARG, enable Foo mode if ARG is
> positive, and disable it otherwise.=C2=A0 If called from Lisp, enable<= br class=3D"gmail_msg"> > the mode if ARG is omitted or nil, and toggle it if ARG is =E2=80=98to= ggle=E2=80=99."
>
> This appears to indicate that (foo-mode 'banana)
> should disable foo-mode, but it enables it.

No, it does not suggest that.=C2=A0 But to be clearer, it should
probably explicitly address the non-nil and non-`toggle' case,
like so:

=C2=A0 If called from Lisp, enable the mode if ARG is omitted or
=C2=A0 nil, toggle it if ARG is =E2=80=98toggle=E2=80=99, and disable it if= ARG is
=C2=A0 any other non-nil value.

(And place the Lisp description in a separate paragraph
from the interactive description.)

> I think minor modes should simply not allow anything but
> integers and 'toggle for ARG, avoiding this confusion.

Why?=C2=A0 There is no confusion possible, once the doc string
explicitly speaks about all possible argument values.

Why would you change the behavior, instead of just clarifying
the doc?

I generall= y prefer the behavior to be as strict as possible. Consider
(foo-= mode 'disable)
If you read such code, do you assume that this= enables foo-mode?
However, in this case I guess it's too lat= e, and fixing the documentation is indeed more appropriate. BTW, the Elisp = manual has the same issue:

=C2=A0 =C2=A0 =C2= =A0The mode command should accept one optional argument.=C2=A0 If called
=C2=A0 =C2=A0 =C2=A0interactively with no prefix argument, it shoul= d toggle the mode
=C2=A0 =C2=A0 =C2=A0(i.e., enable if it is disa= bled, and disable if it is enabled).=C2=A0 If
=C2=A0 =C2=A0 =C2= =A0called interactively with a prefix argument, it should enable the
<= div>=C2=A0 =C2=A0 =C2=A0mode if the argument is positive and disable it oth= erwise.

=C2=A0 =C2=A0 =C2=A0If the mode command is= called from Lisp (i.e., non-interactively),
=C2=A0 =C2=A0 =C2=A0= it should enable the mode if the argument is omitted or =E2=80=98nil=E2=80= =99; it
=C2=A0 =C2=A0 =C2=A0should toggle the mode if the argumen= t is the symbol =E2=80=98toggle=E2=80=99;
=C2=A0 =C2=A0 =C2=A0oth= erwise it should treat the argument in the same way as for an
=C2= =A0 =C2=A0 =C2=A0interactive call with a numeric prefix argument, as descri= bed
=C2=A0 =C2=A0 =C2=A0above.

Pro= bably this should be reworded so that the Lisp case doesn't refer to th= e interactive case at all. Making the documentation obvious is more importa= nt than avoiding repetition.
--001a114699d08ce224053eff699f--