Re: master e4896fc 1/2: Add a new 'flex' completion style

[João Távora]

On Thu, Feb 14, 2019 at 12:38 PM Robert Pluim <address@hidden> wrote:
>
> Unknown <address@hidden> writes:
>
> > diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
> > index b757eb8..c1e3fdc 100644
> > --- a/lisp/minibuffer.el
> > +++ b/lisp/minibuffer.el
> > @@ -788,6 +788,11 @@ Additionally the user can use the char \"*\" as a glob 
> > pattern.")
> >  I.e. when completing \"foo_bar\" (where _ is the position of point),
> >  it will consider all completions candidates matching the glob
> >  pattern \"*foo*bar*\".")
> > +    (flex
> > +     completion-flex-try-completion completion-flex-all-completions
> > +     "Completion of an in-order subset of characters.
> > +When completing \"foo\" the glob \"*f*o*o*\" is used, so that
> > +i.e. foo can complete to frodo.")
>
> I think you can either drop the 'i.e.', or drop 'so that'.

I see it's horrible style, but doesn't seem grammatically wrong.
I fixed it and added quotes to foo and frodo.

> >      (initials
> >       completion-initials-try-completion completion-initials-all-completions
> >       "Completion of acronyms and initialisms.
> > @@ -3345,7 +3350,12 @@ the same set of elements."
> >  ;;; Substring completion
> >  ;; Mostly derived from the code of `basic' completion.
> >
> > -(defun completion-substring--all-completions (string table pred point)
> > +(defun completion-substring--all-completions
> > +    (string table pred point &optional transform-pattern-fn)
> > +  "Match the presumed substring STRING to the entries in TABLE.
> > +Respect PRED and POINT.  The pattern used is a PCM-style
> > +substring pattern, but it be massaged by TRANSFORM-PATTERN-FN, if
> > +that is non-nil."
>
> Iʼm all in favour of respect, but what does that mean in the context
> of PRED and POINT?

It means M-x checkdoc shuts up about it, that's what it means :-)
(or rather flymake's checkdoc backend stops underlining it).

It also means I'll think twice about adding docstrings to functions
I modify, even internal functions.

> What is 'PCM-style'? What does 'massaged' mean? What is the signature of
> TRANSFORM-PATTERN-FN?

"It be" take a pattern, and it be return a pattern.

To be clear, I agree this isn't the best docstring in the world. Is it
better than what was before, which was nothing?  Perhaps that's
arguable and I shouldn't have added it in the first place, forcing
err inviting people like me to go read the source code.  Doing
a good docstring is hard and I usually reserve those efforts for
user-visible functions. You could have very well asked me
what exactly a "PCM-style substring pattern" is, since that's
just as loosely defined as everything else around those
parts.

-- 
João Távora