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

[Robert Pluim]

João Távora <address@hidden> writes:

> On Thu, Feb 14, 2019 at 2:47 PM Robert Pluim <address@hidden> wrote:
>
>> > 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.
>
> I apologize for that paragraph which reads harsher than it means.

No worries: offense can only be taken, never given.

> I was also trying to get your opinion on what is better: writing a
> subpar docstring for an internal function, or keeping it undocumented.

'Incomplete', rather than 'subpar', I think. If a user is likely to
want to call that function directly, then I feel it should have a
docstring. If itʼs purely internal, then itʼs not
necessary. Distinguishing the two cases is hard.

Robert