bug#24095: 25.1; Insufficient documentation of minibuffer-related variables

[Eli Zaretskii <eliz@gnu.org>]

This is a call for people who know their ways around the internals of
completion to please improve the documentation of the related
functions and variables.  I find their current doc strings inadequate,
and their documentation in the ELisp manual simply doesn't exist.

Here's a case in point.  This is a fragment from dired-diff:

  (interactive
   (let* (...
     ...
     (list
      (minibuffer-with-setup-hook
	  (lambda ()
	    (set (make-local-variable 'minibuffer-default-add-function) nil)
	    (setq minibuffer-default defaults))
	(read-file-name
	 (format "Diff %s with%s: " current
		 (if default (format " (default %s)" default) ""))
	 target-dir default t))

Suppose you want to figure out what does the minibuffer-setup-hook try
to accomplish.  Here's the doc string of the 2 variables it uses:

minibuffer-default-add-function:

  Function run by ‘goto-history-element’ before consuming default values.
  This is useful to dynamically add more elements to the list of default values
  when ‘goto-history-element’ reaches the end of this list.
  Before calling this function ‘goto-history-element’ sets the variable
  ‘minibuffer-default-add-done’ to t, so it will call this function only
  once.  In special cases, when this function needs to be called more
  than once, it can set ‘minibuffer-default-add-done’ to nil explicitly,
  overriding the setting of this variable to t in ‘goto-history-element’.

minibuffer-default:

  The current default value or list of default values in the minibuffer.
  The functions ‘read-from-minibuffer’ and ‘completing-read’ bind
  this variable locally.

If you can glean from these doc string (a) what is the significance of
minibuffer-default-add-function being nil, and (b) how the list in
minibuffer-default is used by the completion functions (so you could
decide, for example, what to put there), you are much smarter than I
am.  (The ELisp manual doesn't mention these variables at all.)

Other functions/variables that IMO should be considered for
documentation in the manual:

 minibuffer-avoid-prompt, minibuffer-history-case-insensitive-variables,
 minibuffer-default-add-completions

TIA




In GNU Emacs 25.1.1 (i686-pc-mingw32)
 of 2016-07-24 built on HOME-C4E4A596F7
Windowing system distributor 'Microsoft Corp.', version 5.1.2600
Configured using:
 'configure --prefix=/d/usr --enable-checking=yes,glyphs
 --with-wide-int --with-modules 'CFLAGS=-O2 -gdwarf-4 -g3''

Configured features:
XPM JPEG TIFF GIF PNG RSVG SOUND NOTIFY ACL GNUTLS LIBXML2 ZLIB
TOOLKIT_SCROLL_BARS MODULES

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1255

Major mode: RMAIL

Minor modes in effect:
  shell-dirtrack-mode: t
  diff-auto-refine-mode: t
  desktop-save-mode: t
  save-place-mode: t
  show-paren-mode: t
  display-time-mode: t
  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
  temp-buffer-resize-mode: t
  buffer-read-only: t
  line-number-mode: t

Recent messages:
Auto-saving...done
next-line: End of buffer
Mark set
Sending...
Added to d:/usr/eli/rmail/SENT.MAIL
Sending email 
Sending email done
Sending...done
Showing message 2141...done
Modification-flag cleared

Load-path shadows:
d:/usr/share/emacs/site-lisp/soap-inspect hides d:/usr/share/emacs/25.1/lisp/net/soap-inspect
d:/usr/share/emacs/site-lisp/soap-client hides d:/usr/share/emacs/25.1/lisp/net/soap-client

Features:
(shadow emacsbug tar-mode pulse etags shell grep compile misearch
multi-isearch shr-color color url-util url-parse url-vars shr seq dom
browse-url eieio-opt speedbar sb-image ezimage dframe thingatpt
dabbrev rfc2104 network-stream nsm starttls tls gnutls mail-extr
smtpmail auth-source mailalias sendmail rmailout conf-mode arc-mode
archive-mode org-element org-rmail org-mhe org-irc org-info org-gnus
org-docview doc-view subr-x jka-compr image-mode org-bibtex bibtex
org-bbdb org-w3m org advice org-macro org-footnote org-pcomplete
pcomplete org-list org-faces org-entities org-version ob-emacs-lisp ob
ob-tangle ob-ref ob-lob ob-table ob-exp org-src ob-keys ob-comint
comint ansi-color ob-core ob-eval org-compat org-macs org-loaddefs
find-func cal-menu calendar cal-loaddefs bat-mode make-mode
vc-dispatcher vc-svn parse-time generic vc-cvs vc-bzr bug-reference
add-log info vc-git diff-mode noutline outline easy-mmode flyspell qp
rmailsum rmailmm message dired-x dired format-spec rfc822 mml mml-sec
password-cache epg epg-config gnus-util mm-decode mm-bodies mm-encode
mailabbrev gmm-utils mailheader mail-parse rfc2231 rmail rfc2047
rfc2045 ietf-drums mm-util help-fns mail-prsvr mail-utils desktop
frameset server filecache mairix cus-edit cus-start cus-load wid-edit
saveplace midnight ispell derived generic-x cc-mode cc-fonts cc-guess
cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs paren
xref cl-seq project ring eieio byte-opt bytecomp byte-compile cl-extra
help-mode easymenu cconv eieio-core cl-macs gv cl-loaddefs pcase
cl-lib battery time time-date mule-util tooltip eldoc electric
uniquify ediff-hook vc-hooks lisp-float-type mwheel dos-w32 ls-lisp
disp-table w32-win w32-vars term/common-win tool-bar dnd fontset image
regexp-opt fringe tabulated-list newcomment elisp-mode lisp-mode
prog-mode register page menu-bar rfn-eshadow timer select scroll-bar
mouse jit-lock font-lock syntax facemenu font-core 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 charscript case-table
epa-hook jka-cmpr-hook help simple abbrev 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 w32notify w32 multi-tty
make-network-process emacs)

Memory information:
((conses 16 2191512 214963)
 (symbols 56 42474 0)
 (miscs 48 4368 4900)
 (strings 16 119103 35184)
 (string-bytes 1 3269321)
 (vectors 16 43592)
 (vector-slots 8 1676003 227839)
 (floats 8 540 910)
 (intervals 40 413698 11919)
 (buffers 856 230))