GNU bug report logs - #24607
25.1; comment-dwim doc is confused

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 24607 in the body.
You can then email your comments to 24607 AT debbugs.gnu.org in the normal way.

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

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

From: "liu.huanjie <at> yahoo.com" <liu.huanjie <at> yahoo.com>
To: bug-gnu-emacs <bug-gnu-emacs <at> gnu.org>
Subject: 25.1; comment-dwim doc is confused
Date: Tue, 4 Oct 2016 11:40:52 +0800

[Message part 1 (text/plain, inline)]

   Today I try to write a function that call comment-dwim, it works
when I 'M-x comment-dwim', but when I call it as (comment-dwim), it
says wrong argument number, but after checking the doc and read the
source, I still can't figure out how to give args, which what I want
is the current line where my cursor is.
  I add 'nil' to 'comment-dwim' and fixed, but it will be better to
add something about what args should a caller give, and that will
not confused to at least elisp newbie, and it is better.
  Thanks.



liu.huanjie <at> yahoo.com

[Message part 2 (text/html, inline)]

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

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: "liu.huanjie\@yahoo.com" <liu.huanjie <at> yahoo.com>
Cc: 24607 <at> debbugs.gnu.org
Subject: Re: bug#24607: 25.1; comment-dwim doc is confused
Date: Tue, 13 Feb 2018 22:25:17 -0500

"liu.huanjie <at> yahoo.com" <liu.huanjie <at> yahoo.com> writes:

>    Today I try to write a function that call comment-dwim, it works
> when I 'M-x comment-dwim', but when I call it as (comment-dwim), it
> says wrong argument number, but after checking the doc and read the
> source, I still can't figure out how to give args, which what I want
> is the current line where my cursor is.
>   I add 'nil' to 'comment-dwim' and fixed, but it will be better to
> add something about what args should a caller give, and that will
> not confused to at least elisp newbie, and it is better.

The docstring says

    (comment-dwim ARG)

    [...]
    Else if a prefix ARG is specified, call ‘comment-kill’.

It's a bit terse, but `(elisp) Prefix Command Arguments' says

   * `nil', meaning there is no prefix argument.

as a possible value for prefix arguments.  I don't think we should
explain that again in every function docstring which takes a prefix
argument.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: "liu.huanjie <at> yahoo.com" <liu.huanjie <at> yahoo.com>, 24607 <at> debbugs.gnu.org
Subject: Re: bug#24607: 25.1; comment-dwim doc is confused
Date: Tue, 11 Aug 2020 18:06:44 -0700

tags 24607 + wontfix notabug
close 24607
thanks

Noam Postavsky <npostavs <at> users.sourceforge.net> writes:

> "liu.huanjie <at> yahoo.com" <liu.huanjie <at> yahoo.com> writes:
>
>>    Today I try to write a function that call comment-dwim, it works
>> when I 'M-x comment-dwim', but when I call it as (comment-dwim), it
>> says wrong argument number, but after checking the doc and read the
>> source, I still can't figure out how to give args, which what I want
>> is the current line where my cursor is.
>>   I add 'nil' to 'comment-dwim' and fixed, but it will be better to
>> add something about what args should a caller give, and that will
>> not confused to at least elisp newbie, and it is better.
>
> The docstring says
>
>     (comment-dwim ARG)
>
>     [...]
>     Else if a prefix ARG is specified, call ‘comment-kill’.
>
> It's a bit terse, but `(elisp) Prefix Command Arguments' says
>
>    * `nil', meaning there is no prefix argument.
>
> as a possible value for prefix arguments.  I don't think we should
> explain that again in every function docstring which takes a prefix
> argument.

I agree with Noam here, we shouldn't repeat this information in every
function that takes a prefix argument.

I'm therefore closing this bug report.

Best regards,
Stefan Kangas

Previous Next

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