bug#24607: 25.1; comment-dwim doc is confused

bug#24607: 25.1; comment-dwim doc is confused

[liu.huanjie]

[-- Attachment #1: Type: text/plain, Size: 552 bytes --]

   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@yahoo.com

[-- Attachment #2: Type: text/html, Size: 1563 bytes --]

bug#24607: 25.1; comment-dwim doc is confused

[Noam Postavsky]

"liu.huanjie@yahoo.com" <liu.huanjie@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.

bug#24607: 25.1; comment-dwim doc is confused

[Stefan Kangas]

tags 24607 + wontfix notabug
close 24607
thanks

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

> "liu.huanjie@yahoo.com" <liu.huanjie@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