From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Matt Armstrong Newsgroups: gmane.emacs.bugs Subject: bug#52202: 29.0.50; try-completion, all-completions support for a list of strings COLLECTION is not documented in their docstrings Date: Wed, 01 Dec 2021 11:43:17 -0800 Message-ID: <871r2w2jsa.fsf@rfc20.org> References: <875ys9k2a7.fsf@rfc20.org> <871r2xjvv6.fsf@rfc20.org> <83czmhtp9v.fsf@gnu.org> <87wnkpidim.fsf_-_@rfc20.org> <83sfvdro6q.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="30020"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 52202@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Dec 01 20:51:36 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1msVdg-0007dS-1J for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 01 Dec 2021 20:51:36 +0100 Original-Received: from localhost ([::1]:56664 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1msVdf-0007Nn-4Y for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 01 Dec 2021 14:51:35 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:42092) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1msVWM-0006oq-A1 for bug-gnu-emacs@gnu.org; Wed, 01 Dec 2021 14:44:04 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:34184) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1msVWM-0003pP-1k for bug-gnu-emacs@gnu.org; Wed, 01 Dec 2021 14:44:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1msVWL-0003Sm-UX for bug-gnu-emacs@gnu.org; Wed, 01 Dec 2021 14:44:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Matt Armstrong Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 01 Dec 2021 19:44:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52202 X-GNU-PR-Package: emacs Original-Received: via spool by 52202-submit@debbugs.gnu.org id=B52202.163838780913263 (code B ref 52202); Wed, 01 Dec 2021 19:44:01 +0000 Original-Received: (at 52202) by debbugs.gnu.org; 1 Dec 2021 19:43:29 +0000 Original-Received: from localhost ([127.0.0.1]:45730 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1msVVp-0003Rr-8W for submit@debbugs.gnu.org; Wed, 01 Dec 2021 14:43:29 -0500 Original-Received: from relay2-d.mail.gandi.net ([217.70.183.194]:49379) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1msVVm-0003Re-Vg for 52202@debbugs.gnu.org; Wed, 01 Dec 2021 14:43:27 -0500 Original-Received: (Authenticated sender: matt@rfc20.org) by relay2-d.mail.gandi.net (Postfix) with ESMTPSA id 7A3E040002; Wed, 1 Dec 2021 19:43:20 +0000 (UTC) Original-Received: from matt by naz with local (Exim 4.95) (envelope-from ) id 1msVVd-000NU8-6V; Wed, 01 Dec 2021 11:43:17 -0800 In-Reply-To: <83sfvdro6q.fsf@gnu.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:221232 Archived-At: Eli Zaretskii writes: >> Thanks Eli, I can sympathize with respect to the review difficulty, but >> I couldn't find a simple edit that did a good job. It is more than just >> "list of strings", but I did not realize when I filed the bug. This >> became clear only after I started reading code and trying to document >> the current behavior. > > Can you list the aspects which the current doc string doesn't > describe, or describes inaccurately or incorrectly? Good question; maybe I went overboard. Quotes below are from the current docstring: > If COLLECTION is an alist, the keys (cars of elements) are the > possible completions. If an element is not a cons cell, then the > element itself is the possible completion. I find this confusing because "If COLLECTION is an alist" strongly leads the reader away from the idea that "COLLECTION may also be a list of symbols/strings." So perhaps replace this paragraph with slightly edited text from the manual: If COLLECTION is a list (or alist), the permissible completions are specified by the elements of the list, each of which should be either a string, or a cons cell whose CAR is either a string or a symbol. If the list contains elements of any other type, those are ignored. > The argument given to PREDICATE is the alist element or the symbol > from the obarray. I found this confusing too, for the same reason. So how about: The argument given to PREDICATE is either a string, symbol or a cons cell (the CAR of which is a string or symbol) from the list (or alist), or a symbol (_not_ a symbol name) from the obarray. If COLLECTION is a hash table, PREDICATE is called with two arguments, the string or symbol key and the associated value. These two blurbs are slight edits from the elisp manual. I think this new wording would be good in both the doc string and the manual. If these smaller edits seem good I'm happy to reformulate the patch (I can update the manual as well).