bug#25046: 26.0.50; Arguments of `ediff-janitor' undocumented

bug#25046: 26.0.50; Arguments of `ediff-janitor' undocumented

[Philipp Stephani]

The function `ediff-janitor' has two required arguments, ASK and
KEEP-JANITOR, which are not documented in the docstring.


In GNU Emacs 26.0.50.2 (x86_64-apple-darwin16.1.0, NS appkit-1504.60 Version 10.12.1 (Build 16B2555))
 of 2016-11-27 built on p
Repository revision: 416adda38521c6246f77877c57843264fa4ae711
Windowing system distributor 'Apple', version 10.3.1504
Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Quit
Loading ediff...done
Type C-x 1 to delete the help window.

Configured using:
 'configure --with-modules --enable-checking
 --enable-check-lisp-object-type --without-xml2 --disable-silent-rules
 'CFLAGS=-ggdb3 -O0''

Configured features:
RSVG IMAGEMAGICK DBUS NOTIFY ACL GNUTLS ZLIB TOOLKIT_SCROLL_BARS NS
MODULES

Important settings:
  value of $LANG: de_DE.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-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 subr-x puny seq byte-opt gv
bytecomp byte-compile cconv dired dired-loaddefs format-spec rfc822 mml
mml-sec password-cache epa derived epg epg-config gnus-util rmail
rmail-loaddefs mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums
mm-util mail-prsvr mail-utils ediff-merg ediff-wind ediff-diff
ediff-mult ediff-help ediff-init ediff-util ediff cl-extra thingatpt
help-fns radix-tree help-mode easymenu cl-loaddefs pcase cl-lib
time-date mule-util tooltip eldoc electric uniquify ediff-hook vc-hooks
lisp-float-type mwheel term/ns-win ns-win ucs-normalize term/common-win
tool-bar dnd fontset image regexp-opt fringe tabulated-list replace
newcomment text-mode elisp-mode lisp-mode prog-mode register page
menu-bar rfn-eshadow isearch timer select scroll-bar mouse jit-lock
font-lock syntax facemenu font-core term/tty-colors frame 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
case-table epa-hook jka-cmpr-hook help simple abbrev obarray minibuffer
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 dbusbind kqueue cocoa
ns multi-tty make-network-process emacs)

Memory information:
((conses 16 214548 8247)
 (symbols 48 21296 0)
 (miscs 40 59 218)
 (strings 32 21922 6536)
 (string-bytes 1 726263)
 (vectors 16 36800)
 (vector-slots 8 690820 5774)
 (floats 8 196 20)
 (intervals 56 234 4)
 (buffers 976 12))

bug#25046: 26.0.50; Arguments of `ediff-janitor' undocumented

[Eli Zaretskii]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Sun, 27 Nov 2016 21:30:18 +0100
> 
> The function `ediff-janitor' has two required arguments, ASK and
> KEEP-JANITOR, which are not documented in the docstring.

Thanks, fixed on the emacs-25 branch.

bug#25046: 26.0.50; Arguments of `ediff-janitor' undocumented

[Philipp Stephani]

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

Eli Zaretskii <eliz@gnu.org> schrieb am Fr., 2. Dez. 2016 um 10:30 Uhr:

> > From: Philipp Stephani <p.stephani2@gmail.com>
> > Date: Sun, 27 Nov 2016 21:30:18 +0100
> >
> > The function `ediff-janitor' has two required arguments, ASK and
> > KEEP-JANITOR, which are not documented in the docstring.
>
> Thanks, fixed on the emacs-25 branch.
>

Thanks, however I'm still not quite sure about the meaning.
"ASK non-nil means ask the user whether to keep each unmodified buffer,
unless KEEP-VARIANTS is non-nil, in which case buffers are killed
unconditionally."
So if ASK = nil, KEEP-VARIANTS = nil: kill buffers, don't ask about any
buffer
ASK = (nil or non-nil), KEEP-VARIANTS = non-nil: don't kill any buffer,
don't ask
ASK = non-nil, KEEP-VARIANTS = nil: ask about each buffer

If that's the case, shouldn't the documentation rather be something like:
"If KEEP-VARIANTS is non-nil, only indirect buffers are killed [what does
that mean for the user?], and ASK is ignored. Otherwise, if ASK is non-nil,
ask the user for each unmodified buffer whether it should be killed.
Otherwise (both ASK and KEEP-VARIANTS) are nil, all unmodified buffers are
killed without confirmation."
WDYT?

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

bug#25046: 26.0.50; Arguments of `ediff-janitor' undocumented

[Eli Zaretskii]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Fri, 02 Dec 2016 13:47:33 +0000
> Cc: 25046-done@debbugs.gnu.org
> 
> Thanks, however I'm still not quite sure about the meaning.
> "ASK non-nil means ask the user whether to keep each unmodified buffer, unless KEEP-VARIANTS is
> non-nil, in which case buffers are killed unconditionally."
> So if ASK = nil, KEEP-VARIANTS = nil: kill buffers, don't ask about any buffer

Yes.

> ASK = (nil or non-nil), KEEP-VARIANTS = non-nil: don't kill any buffer, don't ask

Yes, I've goofed.  KEEP-VARIANTS non-nil means never kill.  Now fixed.

> ASK = non-nil, KEEP-VARIANTS = nil: ask about each buffer

Yes.

> If that's the case, shouldn't the documentation rather be something like:
> "If KEEP-VARIANTS is non-nil, only indirect buffers are killed [what does that mean for the user?], and ASK is
> ignored. Otherwise, if ASK is non-nil, ask the user for each unmodified buffer whether it should be killed.
> Otherwise (both ASK and KEEP-VARIANTS) are nil, all unmodified buffers are killed without confirmation."
> WDYT? 

I don't think mentioning indirect buffers will add anything but
confusion.

I fixed the incorrect meaning of KEEP-VARIANTS, and I think the result
is okay, definitely so for an internal utility function.

Thanks.