bug#66147: 28.2; Doc of completion functions: (elisp) `Basic Completion'

[Drew Adams]

What seems missing from this doc (and likewise from the relevant doc
strings) is any description of what it means for a string to _match_
entries in the completion table.

(To be included in an `all-completions' result, or for `try-completion'
or `test-completion' to succeed, successful matches _also_ need to
satisfy the regexps in `completion-regexp-list' and satisfy the
PREDICATE arg.  But those additional, optional conditions are well
enough described - not a problem.)

The information I think is missing is that the basic _matching_ is
literal-prefix completion, that is, string equality between the input
STRING and a prefix of a COLLECTION element (with symbols being treated
as their names etc.).

This should be explicitly pointed out, I think.  There's no regexp
matching, and no substring matching, for example -- nothing but
comparison of the INPUT string literally against the prefixes of the
candidates.

IOW (I think), the matching is this:

 (string-match-p (format "\\`%s" (regexp-quote STRING)) CANDIDATE)

Whether or not that's exactly the matching used, the point is that
whatever kind of matching is used is _not described/specified_.  It
needs to be, for users to understand how these "basic completion
functions" behave.

(One could even mistakenly guess that these functions are sensitive to
the value of `completion-style', so that if that's `substring' then
substring matching would be used.)

In the beginning, Emacs completion used _only_ such literal-prefix
completion, so maybe back then not specifying how an input string is
matched against a completion candidate might not have been so
important.  But nowadays users encounter all kinds of matching when
completing: from substring to flex to regexp,...  They're familiar with
that interactively, as Emacs users, typically long before they encounter
programming with the completion functions described here.


In GNU Emacs 28.2 (build 2, x86_64-w64-mingw32)
 of 2022-09-13 built on AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19045
System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.3324)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation
 --without-compress-install CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS
XPM ZLIB

(NATIVE_COMP present but libgccjit not available)