GNU bug report logs - #4110
23.1.50; Checkdoc should recognize "minor mode"

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 4110 in the body.
You can then email your comments to 4110 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Lennart Borgman <lennart.borgman <at> gmail.com>
To: emacs-pretest-bug <at> gnu.org
Subject: 23.1.50; Checkdoc should recognize "minor mode"
Date: Mon, 10 Aug 2009 23:49:09 +0200

You are not allowed by checkdoc to write "minor mode `my-mode'".
Please allow that.

In GNU Emacs 23.1.50.1 (i386-mingw-nt5.1.2600)
 of 2009-08-01
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags
-Ic:/g/include -fno-crossjumping'

Message #10 received at 4110 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: Lennart Borgman <lennart.borgman <at> gmail.com>
Cc: 4110 <at> debbugs.gnu.org
Subject: Re: 23.1.50; Checkdoc should recognize "minor mode"
Date: Sun, 13 Sep 2009 16:26:59 -0400

> You are not allowed by checkdoc to write "minor mode `my-mode'".
> Please allow that.

Please be specific.

Message #15 received at 4110 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Lennart Borgman <lennart.borgman <at> gmail.com>
To: Chong Yidong <cyd <at> stupidchicken.com>
Cc: 4110 <at> debbugs.gnu.org
Subject: Re: 23.1.50; Checkdoc should recognize "minor mode"
Date: Mon, 14 Sep 2009 00:21:07 +0200

On Sun, Sep 13, 2009 at 10:26 PM, Chong Yidong <cyd <at> stupidchicken.com> wrote:
>> You are not allowed by checkdoc to write "minor mode `my-mode'".
>> Please allow that.
>
> Please be specific.


You can write "function `my-mode'" or "variable `my-mode'" in a doc
string to make checkdoc happy. However I would like to write "minor
mode  `my-mode'" instead since it is more clear. And I think the
`my-mode' link should go to the function since that is wher the doc
string from define-minor-mode shows up.

Message #20 received at 4110 <at> debbugs.gnu.org (full text, mbox):

From: Mauro Aranda <maurooaranda <at> gmail.com>
To: 4110 <at> debbugs.gnu.org
Cc: Lennart Borgman <lennart.borgman <at> gmail.com>
Subject: Re: bug#4110: 23.1.50; Checkdoc should recognize "minor mode"
Date: Mon, 08 Mar 2021 09:04:19 -0300

Lennart Borgman <lennart.borgman <at> gmail.com> writes:

> You can write "function `my-mode'" or "variable `my-mode'" in a doc
> string to make checkdoc happy. However I would like to write "minor
> mode  `my-mode'" instead since it is more clear. And I think the
> `my-mode' link should go to the function since that is wher the doc
> string from define-minor-mode shows up.

The change to allow this should be pretty simple: just add "mode" to the
list of suggested words.

But I do wonder if instead checkdoc should be happy just with the symbol
ending with "-mode".  IOW,  I tend to think that there is no ambiguity
in "`my-mode'" in a docstring, even if my-mode is defined as a variable
and as a function.

Any opinions?

Message #23 received at 4110 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Mauro Aranda <maurooaranda <at> gmail.com>
Cc: Lennart Borgman <lennart.borgman <at> gmail.com>, 4110 <at> debbugs.gnu.org
Subject: Re: bug#4110: 23.1.50; Checkdoc should recognize "minor mode"
Date: Fri, 27 Aug 2021 05:10:08 +0200

Mauro Aranda <maurooaranda <at> gmail.com> writes:

> The change to allow this should be pretty simple: just add "mode" to the
> list of suggested words.
>
> But I do wonder if instead checkdoc should be happy just with the symbol
> ending with "-mode".  IOW,  I tend to think that there is no ambiguity
> in "`my-mode'" in a docstring, even if my-mode is defined as a variable
> and as a function.
>
> Any opinions?

Yes, I think that's a good idea -- requiring "mode" before `my-mode'
seems excessive.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #32 received at 4110 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 4110 <at> debbugs.gnu.org, Lennart Borgman <lennart.borgman <at> gmail.com>,
 Mauro Aranda <maurooaranda <at> gmail.com>
Subject: Re: bug#4110: 23.1.50; Checkdoc should recognize "minor mode"
Date: Fri, 24 Sep 2021 14:45:14 -0700

tags 4110 fixed
close 4110 28.1
thanks

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Mauro Aranda <maurooaranda <at> gmail.com> writes:
>
>> The change to allow this should be pretty simple: just add "mode" to the
>> list of suggested words.
>>
>> But I do wonder if instead checkdoc should be happy just with the symbol
>> ending with "-mode".  IOW,  I tend to think that there is no ambiguity
>> in "`my-mode'" in a docstring, even if my-mode is defined as a variable
>> and as a function.
>>
>> Any opinions?
>
> Yes, I think that's a good idea -- requiring "mode" before `my-mode'
> seems excessive.

I independently arrived at this conclusion, then I found this bug
report.  I agree that there is no confusion, and this check leads to a
ton of such dubious warnings in the Emacs tree.

So I've now fixed this on master (commit 79a9b50621).

Previous Next

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