GNU bug report logs - #31191
26.1; [PATCH] Improve docstring of start-process-shell-command

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 31191 in the body.
You can then email your comments to 31191 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: Damien Cassou <damien <at> cassou.me>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.1; [PATCH] Improve docstring of start-process-shell-command
Date: Tue, 17 Apr 2018 13:39:33 +0200

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

* lisp/subr.el (start-process-shell-command): Add recommended
  signature to docstring. This hides the argument ARGS whose use is
  discouraged. This also makes the argument COMMAND visible so the
  user understands what the docstring is referring to.

-- 
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

[0001-Improve-docstring-of-start-process-shell-command.patch (text/x-patch, attachment)]

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Damien Cassou <damien <at> cassou.me>
Cc: 31191 <at> debbugs.gnu.org
Subject: Re: bug#31191: 26.1;
 [PATCH] Improve docstring of start-process-shell-command
Date: Tue, 17 Apr 2018 07:43:02 -0400

Damien Cassou <damien <at> cassou.me> writes:

> * lisp/subr.el (start-process-shell-command): Add recommended
>   signature to docstring. This hides the argument ARGS whose use is
>   discouraged. This also makes the argument COMMAND visible so the
>   user understands what the docstring is referring to.

> +\(fn NAME BUFFER COMMAND)"
>    (declare (advertised-calling-convention (name buffer command) "23.1"))

I think this is redundant since advertised-calling-convention already
does the same.

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

From: Damien Cassou <damien <at> cassou.me>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 31191 <at> debbugs.gnu.org
Subject: Re: bug#31191: 26.1;
 [PATCH] Improve docstring of start-process-shell-command
Date: Tue, 17 Apr 2018 14:44:17 +0200

Noam Postavsky <npostavs <at> gmail.com> writes:
>> +\(fn NAME BUFFER COMMAND)"
>>    (declare (advertised-calling-convention (name buffer command) "23.1"))
>
> I think this is redundant since advertised-calling-convention already
> does the same.

you are right, thank you. I didn't know about that and helpful does not
take it into account (I've just reported the issue).

What is the preferred way to advertise a signature, the declare form or
a last line in the docstring? If you answer the question, I can fix the
manual to add links between (info "(elisp) Declare Form") and (info
"(elisp) Function Documentation").

-- 
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Damien Cassou <damien <at> cassou.me>
Cc: 31191 <at> debbugs.gnu.org
Subject: Re: bug#31191: 26.1;
 [PATCH] Improve docstring of start-process-shell-command
Date: Tue, 17 Apr 2018 09:06:23 -0400

Damien Cassou <damien <at> cassou.me> writes:

> Noam Postavsky <npostavs <at> gmail.com> writes:
>>> +\(fn NAME BUFFER COMMAND)"
>>>    (declare (advertised-calling-convention (name buffer command) "23.1"))
>>
>> I think this is redundant since advertised-calling-convention already
>> does the same.
>
> you are right, thank you. I didn't know about that and helpful does not
> take it into account (I've just reported the issue).
>
> What is the preferred way to advertise a signature, the declare form or
> a last line in the docstring? If you answer the question, I can fix the
> manual to add links between (info "(elisp) Declare Form") and (info
> "(elisp) Function Documentation").

The advertised-calling-convention declaration should be used when you
want the old way of calling to trigger a warning during byte
compilation.  Otherwise, the docstring method should be used.

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

From: Damien Cassou <damien <at> cassou.me>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 31191 <at> debbugs.gnu.org
Subject: Re: bug#31191: 26.1;
 [PATCH] Improve docstring of start-process-shell-command
Date: Tue, 17 Apr 2018 15:45:16 +0200

On April 17, 2018 3:06:23 PM GMT+02:00, Noam Postavsky <npostavs <at> gmail.com> wrote:
>Damien Cassou <damien <at> cassou.me> writes:
>> What is the preferred way to advertise a signature, the declare form
>or
>> a last line in the docstring? If you answer the question, I can fix
>the
>> manual to add links between (info "(elisp) Declare Form") and (info
>> "(elisp) Function Documentation").
>
>The advertised-calling-convention declaration should be used when you
>want the old way of calling to trigger a warning during byte
>compilation.  Otherwise, the docstring method should be used.

Thank you. Can you please close this issue? I will send a patch within another report.
-- 
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Damien Cassou <damien <at> cassou.me>
Cc: 31191 <at> debbugs.gnu.org
Subject: Re: bug#31191: 26.1;
 [PATCH] Improve docstring of start-process-shell-command
Date: Tue, 17 Apr 2018 18:44:51 -0400

forwarded 31191 https://github.com/Wilfred/helpful/issues/104
close 31191
quit

Damien Cassou <damien <at> cassou.me> writes:

> Thank you. Can you please close this issue? I will send a patch within another report.

Sure thing.

Previous Next

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