Subject: Re: bug#43307: 28.0.50; `diff-no-select': no documentation for BUF argument

From: Eli Zaretskii <[email-masked]>
Date: Fri, 11 Sep 2020 09:07:54 +0300

> From: Lars Ingebrigtsen <[email-masked]>
> Date: Thu, 10 Sep 2020 23:04:14 +0200
> Cc: [email-masked]
> 
> Philipp Stephani <[email-masked]> writes:
> 
> > The signature for `diff-no-select' is:
> >
> > (diff-no-select OLD NEW &optional SWITCHES NO-ASYNC BUF)
> >
> > Its docstring refers to `diff' for the meaning of the arguments, but
> > `diff' doesn't take an argument, so BUF is undocumented.
> >
> > Probably `diff-no-select' should also document that the return value is
> > BUF if BUF is non-nil.
> 
> I've now amended the doc string of the function on Emacs 28.

Thanks, but please backport this to the release branch, as doc changes
should be installed there.

Also, the new doc string of diff-no-select uses too much of passive
tense; can we improve that?

And finally, the SWITCHES argument is left semi-documented, since the
doc string of 'diff' doesn't tell what happens in non-interactive
calls if SWITCHES is specified, and doesn't say what should be its
form in that case.