From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail
From: Robert Pluim <rpluim@gmail.com>
Newsgroups: gmane.emacs.devel
Subject: Re: master e4896fc 1/2: Add a new 'flex' completion style
Date: Thu, 14 Feb 2019 16:12:03 +0100
Message-ID: <m2o97ez9oc.fsf@gmail.com>
References: <20190213212413.868.40960@vcs0.savannah.gnu.org>
	<20190213212414.D6F4C209C6@vcs0.savannah.gnu.org>
	<m2zhqyzgrp.fsf@gmail.com>
	<CALDnm53DycrwnymFVOYSH+90wrJcqTRkQ9Q45YfJrNBj+dLWRg@mail.gmail.com>
	<m2sgwqzatz.fsf@gmail.com>
	<CALDnm51pCh5Cg+fvwiHwGbQjWHYvFofgfr8p5hvhTQTF42yBwA@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226";
	logging-data="46458"; mail-complaints-to="usenet@blaine.gmane.org"
Cc: emacs-devel <emacs-devel@gnu.org>
To: =?utf-8?B?Sm/Do28gVMOhdm9yYQ==?= <joaotavora@gmail.com>
Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Feb 14 16:13:59 2019
Return-path: <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>
Envelope-to: ged-emacs-devel@m.gmane.org
Original-Received: from lists.gnu.org ([209.51.188.17])
	by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>)
	id 1guIi7-000Buz-GQ
	for ged-emacs-devel@m.gmane.org; Thu, 14 Feb 2019 16:13:59 +0100
Original-Received: from localhost ([127.0.0.1]:49947 helo=lists.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>)
	id 1guIi6-0002WU-GI
	for ged-emacs-devel@m.gmane.org; Thu, 14 Feb 2019 10:13:58 -0500
Original-Received: from eggs.gnu.org ([209.51.188.92]:51602)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <rpluim@gmail.com>) id 1guIgl-0002Vt-2p
	for emacs-devel@gnu.org; Thu, 14 Feb 2019 10:12:35 -0500
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <rpluim@gmail.com>) id 1guIgJ-00038o-Ch
	for emacs-devel@gnu.org; Thu, 14 Feb 2019 10:12:08 -0500
Original-Received: from mail-wm1-x334.google.com ([2a00:1450:4864:20::334]:52161)
	by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16)
	(Exim 4.71) (envelope-from <rpluim@gmail.com>) id 1guIgJ-00038b-4h
	for emacs-devel@gnu.org; Thu, 14 Feb 2019 10:12:07 -0500
Original-Received: by mail-wm1-x334.google.com with SMTP id b11so6692737wmj.1
	for <emacs-devel@gnu.org>; Thu, 14 Feb 2019 07:12:07 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025;
	h=from:to:cc:subject:references:date:in-reply-to:message-id
	:mime-version:content-transfer-encoding;
	bh=0S7iIZk4s88Vk1fYEifqoOBQQnJJztZPhrolmIzU21g=;
	b=hem0XAhWdFqdnnxZDu4x7LcaNvGNQV8+kfaCG/ULXM3RsEuHpx09qP6BsSuI8ttBfq
	qeK2/EscGPJT/rRvwX3xBbCuZvtnX9YMLtYbeklsxGyJhTB+l8YI8ZB2wFJHMhFC1kjz
	z4vCa0T45UrcpyG9lYIcNT14II61qwOI8fL9zNkMzVkOA91SI7he84k71MG/Gz2ZcsFb
	BR0q0sobqENS3ciJtqIfS+zvTWtcYVHbeOO0/Id4+Fw5dPE2ykRIPMSRlTBlRGLMh2sn
	RFRZcwrXLT93EgdWXyDziDIYz0B/gBM+OmYzDd99NKUk1v99yS1n70YbpqdA12J0+O61
	ZdgQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
	d=1e100.net; s=20161025;
	h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to
	:message-id:mime-version:content-transfer-encoding;
	bh=0S7iIZk4s88Vk1fYEifqoOBQQnJJztZPhrolmIzU21g=;
	b=i6yB6a/sUd2DbfEdwQX32cryFOVVjNFFY4YpOMmTUcWCbu4rl98fFK4LHp5fRUYFll
	w1EEjZtiUnBI12WSLOd2CDMeDPGU1qNqKAtQwOPEvbLWotVivyQLyGC+9jyuIFT464eE
	F9rinmDlzjqVLNtN83tfddoAiWQf/vRbs7BZYpOJVIWKYry0RzqvTu/SQsmwqSaPwQeH
	+7EFV34d5RBYkF+uIUkebN6W5MBuW/a7XTbH7qRtIooIrdclTUA0dOKSUNJn4oOJ2USr
	BELxInELWsrrAOJt2npvcF1HbdH5Tb3prjzFqYKMdip8F6FrDEQ2x3XGNm0sj745axO7
	jfXA==
X-Gm-Message-State: AHQUAubN2RI6VIa84M4kLmJoeA57f1uKypKgIxI30mawgrWBE1hKF6gA
	+YodtcVWkGFLpCKMJQXXwrhycQVo
X-Google-Smtp-Source: AHgI3IbkupnDhUw59TioC2Qv/SnSBHaCsupcJCK3NVrQrNlf3TypkvLvI5BmUvTMNP6rn0v8xdISNg==
X-Received: by 2002:a1c:c181:: with SMTP id r123mr3074219wmf.8.1550157125466; 
	Thu, 14 Feb 2019 07:12:05 -0800 (PST)
Original-Received: from rpluim-mac ([149.5.228.1])
	by smtp.gmail.com with ESMTPSA id d9sm4264747wrn.72.2019.02.14.07.12.04
	(version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256);
	Thu, 14 Feb 2019 07:12:04 -0800 (PST)
In-Reply-To: <CALDnm51pCh5Cg+fvwiHwGbQjWHYvFofgfr8p5hvhTQTF42yBwA@mail.gmail.com>
	(=?utf-8?Q?=22Jo=C3=A3o_T=C3=A1vora=22's?= message of "Thu, 14 Feb 2019
	14:50:45 +0000")
X-detected-operating-system: by eggs.gnu.org: Genre and OS details not
	recognized.
X-Received-From: 2a00:1450:4864:20::334
X-BeenThere: emacs-devel@gnu.org
X-Mailman-Version: 2.1.21
Precedence: list
List-Id: "Emacs development discussions." <emacs-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-devel>,
	<mailto:emacs-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/emacs-devel/>
List-Post: <mailto:emacs-devel@gnu.org>
List-Help: <mailto:emacs-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-devel>,
	<mailto:emacs-devel-request@gnu.org?subject=subscribe>
Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org
Original-Sender: "Emacs-devel" <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>
Xref: news.gmane.org gmane.emacs.devel:233323
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/233323>

Jo=C3=A3o T=C3=A1vora <joaotavora@gmail.com> writes:

> On Thu, Feb 14, 2019 at 2:47 PM Robert Pluim <rpluim@gmail.com> 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=CA=BCs purely internal, then it=CA=BCs not
necessary. Distinguishing the two cases is hard.

Robert