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 15:47:04 +0100
Message-ID: <m2sgwqzatz.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>
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="208594"; 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 15:52:21 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 1guINA-000s9F-P9
	for ged-emacs-devel@m.gmane.org; Thu, 14 Feb 2019 15:52:20 +0100
Original-Received: from localhost ([127.0.0.1]:49689 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 1guIN9-0002kZ-My
	for ged-emacs-devel@m.gmane.org; Thu, 14 Feb 2019 09:52:19 -0500
Original-Received: from eggs.gnu.org ([209.51.188.92]:46888)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <rpluim@gmail.com>) id 1guIMz-0002gE-NY
	for emacs-devel@gnu.org; Thu, 14 Feb 2019 09:52:11 -0500
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <rpluim@gmail.com>) id 1guII8-0006fG-LQ
	for emacs-devel@gnu.org; Thu, 14 Feb 2019 09:47:10 -0500
Original-Received: from mail-wm1-x32e.google.com ([2a00:1450:4864:20::32e]:37770)
	by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16)
	(Exim 4.71) (envelope-from <rpluim@gmail.com>) id 1guII8-0006ck-FD
	for emacs-devel@gnu.org; Thu, 14 Feb 2019 09:47:08 -0500
Original-Received: by mail-wm1-x32e.google.com with SMTP id x10so6308429wmg.2
	for <emacs-devel@gnu.org>; Thu, 14 Feb 2019 06:47: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=vsZaRxaq5JUWej3mqxVE9LHOHfjgnY9AFG7vmNFBDQU=;
	b=pmwhS7ebmHI2JaX7wXCi/lV9RIh8CcG6d+oDK/tHlmYPlM2H2mInDuMSNnN2IKb+UO
	z1UIkyLRunPBmoB0wV66PAP7gRnj4CdOKtTJuqWCqD+X55Ms+8Mf+psS/60xQfNzk55r
	LnRzbshPtad784JFnfq1Edl4JzerIiN0PwwU4lW4roEtR3Tv9aGx0co52lSCy3+jxgxa
	jf0PyAEmqzYZVdolsT+06/QeF3uS44JpTajFip96Ti6TxMMyWS54rOoPUnFgOTWtWb8V
	6SfjGqHIJRq+AzzUg8740uaaPuNw6GrS1A14UN7zOnfMKYLTmF8R4a2ZcFi1O5l09Ok9
	kCGQ==
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=vsZaRxaq5JUWej3mqxVE9LHOHfjgnY9AFG7vmNFBDQU=;
	b=J1SaH3jtZunedj2nApzpw8PuWoP6oOqrbeNFmDO2HlodYGSTm4es7HjFj6TC5zusGT
	IGlHfSsq56DLf9HI/JFXEVmgA12OrlzsEgLIJpMeNKn0G06yfI5SAKPZRxRKYYt7Xme0
	RW8uCnHeaVx48TQo7Odjno/dvRtXA5e6vMfoeFnrgz6qBhnKY1u1LrVq7ZYzNbYbLV9F
	T6ntEgyGBsFONlaTxCyYs1mk4rkr8AUxpsiKd4BAwiCdIoU6wdiDqzaapcrCkoYe/ZQl
	+dr41YjeRroCaX7M3fXZe3R1wnfMeYyurhIE/+1dHdbMhWoMnf83MG5/W4tc3qQRC2lX
	61Qg==
X-Gm-Message-State: AHQUAubDy1aUL4lbIFH6cZQ02w6L2S/BI4MBCPUvIq5b6Z/l8CHzLmEr
	LYF74pD4prEbswwQEF/ulH1z82Ta
X-Google-Smtp-Source: AHgI3IYLmbJBaPWnkwzGaOLBLwoejNuvLX7Z8hNtGeprMORRUY6i4FntcoN+4ZEtinxpXl7yhDezhw==
X-Received: by 2002:a1c:c60b:: with SMTP id w11mr3008544wmf.39.1550155626124; 
	Thu, 14 Feb 2019 06:47:06 -0800 (PST)
Original-Received: from rpluim-mac ([149.5.228.1]) by smtp.gmail.com with ESMTPSA id
	q21sm3180526wmc.14.2019.02.14.06.47.04
	(version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256);
	Thu, 14 Feb 2019 06:47:04 -0800 (PST)
In-Reply-To: <CALDnm53DycrwnymFVOYSH+90wrJcqTRkQ9Q45YfJrNBj+dLWRg@mail.gmail.com>
	(=?utf-8?Q?=22Jo=C3=A3o_T=C3=A1vora=22's?= message of "Thu, 14 Feb 2019
	13:50:15 +0000")
X-detected-operating-system: by eggs.gnu.org: Genre and OS details not
	recognized.
X-Received-From: 2a00:1450:4864:20::32e
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:233319
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/233319>

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

>> >      (initials
>> >       completion-initials-try-completion completion-initials-all-compl=
etions
>> >       "Completion of acronyms and initialisms.
>> > @@ -3345,7 +3350,12 @@ the same set of elements."
>> >  ;;; Substring completion
>> >  ;; Mostly derived from the code of `basic' completion.
>> >
>> > -(defun completion-substring--all-completions (string table pred point)
>> > +(defun completion-substring--all-completions
>> > +    (string table pred point &optional transform-pattern-fn)
>> > +  "Match the presumed substring STRING to the entries in TABLE.
>> > +Respect PRED and POINT.  The pattern used is a PCM-style
>> > +substring pattern, but it be massaged by TRANSFORM-PATTERN-FN, if
>> > +that is non-nil."
>>
>> I=CA=BCm all in favour of respect, but what does that mean in the context
>> of PRED and POINT?
>
> It means M-x checkdoc shuts up about it, that's what it means :-)
> (or rather flymake's checkdoc backend stops underlining it).
>
> It also means I'll think twice about adding docstrings to functions
> I modify, even internal functions.
>
>> What is 'PCM-style'? What does 'massaged' mean? What is the signature of
>> TRANSFORM-PATTERN-FN?
>
> "It be" take a pattern, and it be return a pattern.
>
> 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.

Thank you for the changes in any case.

Robert