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

[Noam Postavsky]

Damien Cassou <damien@cassou.me> writes:

> Noam Postavsky <npostavs@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.