[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.
Robert