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: Tue, 30 Nov 2021 12:39:45 -0800 Message-ID: <87wnkpidim.fsf_-_@rfc20.org> References: <875ys9k2a7.fsf@rfc20.org> <871r2xjvv6.fsf@rfc20.org> <83czmhtp9v.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="37805"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) 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 Tue Nov 30 21:40:10 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 1ms9v8-0009aU-Mw for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 30 Nov 2021 21:40:10 +0100 Original-Received: from localhost ([::1]:46736 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ms9v7-0005g3-7B for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 30 Nov 2021 15:40:09 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:33978) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ms9v0-0005fv-JX for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2021 15:40:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:59319) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ms9v0-0006mY-BH for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2021 15:40:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ms9v0-00040x-8t for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2021 15:40:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Matt Armstrong Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 30 Nov 2021 20:40:02 +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.163830479715414 (code B ref 52202); Tue, 30 Nov 2021 20:40:02 +0000 Original-Received: (at 52202) by debbugs.gnu.org; 30 Nov 2021 20:39:57 +0000 Original-Received: from localhost ([127.0.0.1]:42632 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ms9uv-00040X-Fk for submit@debbugs.gnu.org; Tue, 30 Nov 2021 15:39:57 -0500 Original-Received: from relay8-d.mail.gandi.net ([217.70.183.201]:39929) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ms9ut-00040B-CV for 52202@debbugs.gnu.org; Tue, 30 Nov 2021 15:39:56 -0500 Original-Received: (Authenticated sender: matt@rfc20.org) by relay8-d.mail.gandi.net (Postfix) with ESMTPSA id B7D961BF206; Tue, 30 Nov 2021 20:39:48 +0000 (UTC) Original-Received: from matt by naz with local (Exim 4.95) (envelope-from ) id 1ms9uj-000HYA-Se; Tue, 30 Nov 2021 12:39:45 -0800 In-Reply-To: <83czmhtp9v.fsf@gnu.org> (Eli Zaretskii's message of "Tue, 30 Nov 2021 21:30:20 +0200") 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:221176 Archived-At: Eli Zaretskii writes: >> From: Matt Armstrong >> Date: Tue, 30 Nov 2021 11:18:05 -0800 >> >> Attached is a docstring patch against the emacs-28 branch for this >> issue. > > Thanks, but ... all these changes just to say that a list of strings > can also be a COLLECTION? This looks like a complete rewrite, and > comparing it with the existing doc string is a lot of work. Is the > current doc string really that awful and requires such a complete > rewrite? Why can't we get away with a smaller, simpler change (that > would be easier to review and approve)? 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. Then I realized that the lisp reference manual is in good shape. This patch copies text almost verbatim from it. So, the diff is both large but hopefully not hard to verify in review. Another issue is that these function provide extension points that pass COLLECTION or elements from it directly to caller-supplied functions. To write those functions correctly the programmer has to know all the details of how the default C implementation works if the callbacks are to work in a robust way. In other words, this docstring is for completion extension implementers as much as it is for callers. I figure an exhaustively pedantic approach is justifiable here. One problem is the semantic complexity of how these functions interpret COLLECTION. They defy a simple and concise explanation. E.g. COLLECTION can be... ...a list of strings ...a list of symbols ...an alist whose keys are strings ...an alist whose keys are symbols ...a list whose elements are a mixture of any of the above four possibilities. And we have hash tables whose keys are strings, symbols, or a mix... Also, any PREDICATE is passed the list elements (or hash key/values) directly, without any symbol->string normalization. Little of this is clear from the current docstrings, but the lisp ref does a good job with it. >> Note/question: I wonder if the `all-completions' docstring should refer >> to `try-completion' rather than copy much of the text. The same >> approach works well in the lisp ref manual, I think. > > ELisp manual describes both one next to the other, so it can get away > with such a technique. Doc strings don't have that luxury; referring > the user to another complex doc string generally raises the bar and > makes the documentation harder to use, because one needs to constantly > go back to the original function to figure out how the arguments > described in the other function are used in the original one. It's > annoying. That makes sense, thanks.