[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: master e4896fc 1/2: Add a new 'flex' completion style
From: |
Robert Pluim |
Subject: |
Re: master e4896fc 1/2: Add a new 'flex' completion style |
Date: |
Thu, 14 Feb 2019 15:47:04 +0100 |
João Távora <address@hidden> writes:
>> > (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.
Doing good docstrings is hard, which is why there will always be
comments on them. Such comments are exactly that: comments, not
criticism.
Thank you for the changes in any case.
Robert