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

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

[Philipp Stephani]

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.


In GNU Emacs 28.0.50 (build 6, x86_64-pc-linux-gnu, GTK+ Version 3.24.20, cairo version 1.16.0)
 of 2020-09-10
Repository revision: 5d522b430bd5ecfb8f082906cd634883dbb68f3e
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12008000
System Description: Debian GNU/Linux rodete

Configured using:
 'configure --enable-gcc-warnings=warn-only
 --enable-gtk-deprecation-warnings --without-pop --with-mailutils
 --enable-checking=all --enable-check-lisp-object-type --with-modules
 'CFLAGS=-O1 -ggdb3 -fno-omit-frame-pointer -fsanitize=address
 -fsanitize=undefined''

Configured features:
XPM JPEG TIFF GIF PNG CAIRO SOUND DBUS GSETTINGS GLIB NOTIFY INOTIFY
LIBSELINUX GNUTLS FREETYPE HARFBUZZ ZLIB TOOLKIT_SCROLL_BARS GTK3 X11
XDBE XIM MODULES THREADS LIBSYSTEMD JSON PDUMPER

Important settings:
  value of $LANG: en_US.utf8
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc dired dired-loaddefs rfc822
mml easymenu mml-sec epa epg epg-config gnus-util rmail rmail-loaddefs
text-property-search time-date mm-decode mm-bodies mm-encode mail-parse
rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045
ietf-drums mm-util mail-prsvr mail-utils phst skeleton derived edmacro
kmacro pcase ffap thingatpt url url-proxy url-privacy url-expand
url-methods url-history url-cookie url-domsuf url-util url-parse
auth-source cl-seq eieio eieio-core cl-macs eieio-loaddefs
password-cache json map url-vars mailcap subr-x rx gnutls puny seq
byte-opt gv bytecomp byte-compile cconv dbus xml compile comint
ansi-color ring cl-loaddefs cl-lib tooltip eldoc electric uniquify
ediff-hook vc-hooks lisp-float-type mwheel term/x-win x-win
term/common-win x-dnd tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode elisp-mode lisp-mode
prog-mode register page tab-bar menu-bar rfn-eshadow isearch timer
select scroll-bar mouse jit-lock font-lock syntax facemenu font-core
term/tty-colors frame minibuffer cl-generic cham georgian utf-8-lang
misc-lang vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms
cp51932 hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese composite charscript charprop case-table epa-hook
jka-cmpr-hook help simple abbrev obarray cl-preloaded nadvice loaddefs
button faces cus-face macroexp files text-properties overlay sha1 md5
base64 format env code-pages mule custom widget hashtable-print-readable
backquote threads dbusbind inotify dynamic-setting system-font-setting
font-render-setting cairo move-toolbar gtk x-toolkit x multi-tty
make-network-process emacs)

Memory information:
((conses 16 70103 5731)
 (symbols 48 8619 1)
 (strings 32 23908 2163)
 (string-bytes 1 780262)
 (vectors 16 14608)
 (vector-slots 8 195365 11437)
 (floats 8 26 31)
 (intervals 56 225 0)
 (buffers 992 11))

-- 
Google Germany GmbH
Erika-Mann-Straße 33
80636 München

Geschäftsführer: Paul Manicle, Halimah DeLaine Prado
Registergericht und -nummer: Hamburg, HRB 86891
Sitz der Gesellschaft: Hamburg

Diese E-Mail ist vertraulich.  Falls Sie diese fälschlicherweise erhalten haben
sollten, leiten Sie diese bitte nicht an jemand anderes weiter, löschen Sie
alle Kopien und Anhänge davon und lassen Sie mich bitte wissen, dass die E-Mail
an die falsche Person gesendet wurde.

This e-mail is confidential.  If you received this communication by mistake,
please don’t forward it to anyone else, please erase all copies and
attachments, and please let me know that it has gone to the wrong person.

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

[Lars Ingebrigtsen]

Philipp Stephani <p.stephani2@gmail.com> 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.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Thu, 10 Sep 2020 23:04:14 +0200
> Cc: 43307@debbugs.gnu.org
> 
> Philipp Stephani <p.stephani2@gmail.com> 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.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

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

I've taken a what of it.

> 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.

I've now removed the punting to diff and just explained the options in
this doc string.

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

If the final result now looks OK, I can backport it.  It didn't seem
important enough (it's an internal function) to me, though.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: p.stephani2@gmail.com,  43307@debbugs.gnu.org
> Date: Fri, 11 Sep 2020 14:27:48 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Also, the new doc string of diff-no-select uses too much of passive
> > tense; can we improve that?
> 
> I've taken a what of it.
> 
> > 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.
> 
> I've now removed the punting to diff and just explained the options in
> this doc string.
> 
> > Thanks, but please backport this to the release branch, as doc changes
> > should be installed there.
> 
> If the final result now looks OK, I can backport it.  It didn't seem
> important enough (it's an internal function) to me, though.

I think you forgot to push...

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> I think you forgot to push...

Indeed.  Now pushed.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: p.stephani2@gmail.com,  43307@debbugs.gnu.org
> Date: Fri, 11 Sep 2020 14:40:22 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I think you forgot to push...
> 
> Indeed.  Now pushed.

Thanks, LGTM.  Although I would add that SWITCHES should be a list of
command-line switches.

And yes, let's backport this to the release branch.  I agree that this
is not very important, but backporting is easy.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, LGTM.  Although I would add that SWITCHES should be a list of
> command-line switches.
>
> And yes, let's backport this to the release branch.  I agree that this
> is not very important, but backporting is easy.

Yup; I've now added that bit about SWITCHES and copied to emacs-27.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no