[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: João Távora
Subject: Re: master e4896fc 1/2: Add a new 'flex' completion style
Date: Thu, 14 Feb 2019 14:50:45 +0000

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.

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


reply via email to

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