[Top][All Lists]

[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 16:12:03 +0100

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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]