From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Robert Pluim 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: References: <20190213212413.868.40960@vcs0.savannah.gnu.org> <20190213212414.D6F4C209C6@vcs0.savannah.gnu.org> 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 To: =?utf-8?B?Sm/Do28gVMOhdm9yYQ==?= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Feb 14 16:13:59 2019 Return-path: 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 ) 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 ) 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 ) 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 ) 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 ) 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 ; 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: (=?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." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:233323 Archived-At: Jo=C3=A3o T=C3=A1vora writes: > On Thu, Feb 14, 2019 at 2:47 PM Robert Pluim 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