From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: =?UTF-8?Q?Jo=C3=A3o_?= =?UTF-8?Q?T=C3=A1vora?= Newsgroups: gmane.emacs.bugs Subject: bug#41531: 27.0.91; Better handle asynchronous eldoc backends Date: Sat, 04 Jul 2020 12:00:57 +0100 Message-ID: <87zh8fsfx2.fsf@gmail.com> References: <875zckuet9.fsf@gmail.com> <87sgecssch.fsf@gmail.com> <83k0zjvi4c.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="25105"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: 41531@debbugs.gnu.org, monnier@iro.umontreal.ca, andreyk.mad@gmail.com, dgutov@yandex.ru To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Jul 04 13:02:12 2020 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 1jrfvw-0006RB-Hd for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 04 Jul 2020 13:02:12 +0200 Original-Received: from localhost ([::1]:56120 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jrfvv-0005FV-Jf for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 04 Jul 2020 07:02:11 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:48396) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jrfvm-0005Dp-In for bug-gnu-emacs@gnu.org; Sat, 04 Jul 2020 07:02:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:46599) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jrfvm-0006X7-9R for bug-gnu-emacs@gnu.org; Sat, 04 Jul 2020 07:02:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jrfvm-0005nw-0V for bug-gnu-emacs@gnu.org; Sat, 04 Jul 2020 07:02:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: =?UTF-8?Q?Jo=C3=A3o_?= =?UTF-8?Q?T=C3=A1vora?= Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 04 Jul 2020 11:02:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 41531 X-GNU-PR-Package: emacs Original-Received: via spool by 41531-submit@debbugs.gnu.org id=B41531.159386047122247 (code B ref 41531); Sat, 04 Jul 2020 11:02:01 +0000 Original-Received: (at 41531) by debbugs.gnu.org; 4 Jul 2020 11:01:11 +0000 Original-Received: from localhost ([127.0.0.1]:58145 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jrfuw-0005mk-BC for submit@debbugs.gnu.org; Sat, 04 Jul 2020 07:01:11 -0400 Original-Received: from mail-wm1-f51.google.com ([209.85.128.51]:52438) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jrfut-0005mL-8x for 41531@debbugs.gnu.org; Sat, 04 Jul 2020 07:01:08 -0400 Original-Received: by mail-wm1-f51.google.com with SMTP id q15so34296552wmj.2 for <41531@debbugs.gnu.org>; Sat, 04 Jul 2020 04:01:07 -0700 (PDT) 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 :user-agent:mime-version:content-transfer-encoding; bh=U3jKGvVmvC7vW5tZ6ATbgPWsl1l0Ym+M8Adx0n2gwtM=; b=a8w0HHzthl0KBxDztsqb26qWqRTw9LSympDtrr/UoAvyXgisqYUCrnrO1cV5x5+wUy z1Mk86nUPEQLhGM9ksLWvFPb6cTnxRTMPKtZSveNc30T+daWqxfrZ/58TeJHoIUZiKgX SynvRhUqRo7Qvy2FAW0ti/5sAJ6u5nbmsvoxSzPYgY1LJpAwWpWJcM6dF/FwlUT+5jtR Vl5vt7ro1x4Sa1ZORGympJs3e1hKyx3T1it6PKoopu+6DhI8uX4OfCGCzG38OJMcqdVG DzCStgS98ZEuw8KPXa3wSo9Y7d8E7xHS5ZxDEphFllyuuQSIB8PkYnI9eiaxbLi5TWi5 LgcQ== 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:user-agent:mime-version:content-transfer-encoding; bh=U3jKGvVmvC7vW5tZ6ATbgPWsl1l0Ym+M8Adx0n2gwtM=; b=fDaC39usPtCY05SRUbBbwYSBHXCWuPwKG3r2BpIZb7BCUr17DjCPkeRpaHMBZPkcaQ /MWZOUB5lADHR0lv/hyhNx5vP1vAQ6VJstipKXXBzrvH53XPw8apNlpWWYMqLf1ksq0u Qw2mv8IDinkRlw6PCWW9LnH5ZMN4lPnQeAXOGqu0vOn7Vje6c7EDndNHE9zHJonzxB51 pbpAtWY64ug/h9pq9tjCwU06qetfocTSgi+qW2BaOF69lXBGdbVr9VQDSprUkU7ehyXK rqG2xwYpxXc5y3QQuDy6ZpKfjHZ+ayQJ5ERuwd/MltiN0DwOd350H7XSVX4IOah8oj/P MXoA== X-Gm-Message-State: AOAM5318BVwtfhjc6EmTiwWaSS0jEZwA8EAmB8Khqiir9l1uPPic0lWM 9FZ7IvuVEQXJbd5zJbdw+bk= X-Google-Smtp-Source: ABdhPJxpwLDg2TPW7LnFRPoHM1Mf5aSUhP68r8FgO9YCZX5ecE9QDseclYgKJfwEJCI/RR6HbWAnJw== X-Received: by 2002:a7b:c18f:: with SMTP id y15mr41408824wmi.85.1593860461240; Sat, 04 Jul 2020 04:01:01 -0700 (PDT) Original-Received: from krug ([2001:818:d820:9500:824a:171:15a:2213]) by smtp.gmail.com with ESMTPSA id k185sm16389237wmk.47.2020.07.04.04.00.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 04 Jul 2020 04:01:00 -0700 (PDT) In-Reply-To: <83k0zjvi4c.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 04 Jul 2020 10:45:07 +0300") 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:182689 Archived-At: Eli Zaretskii writes: >> Anyway I think my efforts are ready to push to master. I'll do so soon >> unless someone raises a serious problem about it. > > Not a serious problem, but some comments: > >> -(defun eldoc-message (&optional string) >> +(make-obsolete >> + 'eldoc-message "use `eldoc-documentation-functions' instead." "1.1.0") > > Isn't the version part of the obsolete message supposed to tell the > version of Emacs? Yes, but eldoc.el is its own versioned piece of software now, because it is a GNU Elpa :core package. So I opted to use that versioning instead. Maybe I shouldn't have? Don't know if there's prior art for this situation, but I'm reasonably confident I personally have taken this decision before. > The change to the number of arguments of the functions in the > eldoc-documentation-functions hook is backward-incompatible, isn't it? > I see you've changed the relevant functions in our sources, but what > about 3rd-party packages? I've checked and there were none. The eldoc-documentation-functions variable came to be in Emacs master: it's not in Emacs 27. I myself "released" eldoc.el to GNU Elpa almost 2 months ago (see 9ebf51999ce58cccc2a228fd07a18c7b472dd3fd). I had intended to streamline that release together with these async-related developments, but reality (and mostly Dmitry :-) intervened. So indeed there is the danger that, in the intervening 2 months, some 3rd party package depending on GNU Elpa's Eldoc, started using the argless eldoc-documentation-functions, and will be surprised by this backwards-incompatible change. However, I think the changes of that are unlikely. I searched Github and Google for such references and couldn't find any. So I think it's safe. (But even if it weren't, I'd still argue for the change + fallout ). > Also, the doc string of this hook needs clarification regarding the > arguments: it first says that CALLBACK is the only mandatory argument > to the hook functions, but then, out of the blue, appear additional > arguments DOCSTRING and a list of key-value pairs. Confusing. Understood. > The doc strings have some words in UK English spelling "(e.g., > "honour"), please fix that. Also, please make sure comments all start > with a capital letter, end with a period, and comprise full English > sentences. OK. > The doc string of eldoc-documentation-compose doesn't say a word about > the function's argument. That function isn't meant to be called by users, and the EAGERLYP is a code-saving trick. But of course I should document it. > In the doc string of eldoc-documentation-strategy, you use the phrase > "queries the special hook for all functions that produce doc strings" > to mean, AFAIU, that the specified functions in the hook-variable list > are called. IMO, this wording could be confusing; suggest to use this > instead: > > `eldoc-documentation-compose': calls all the functions in the hook, > and displays all of the resulting doc strings ... This of course, assumes that people know that "functions in the hook" aren't like "functions in a list". The symbol `t` may be in "in the hook". But it's better for practical purposed, I admit. Because "result" is often conflated with "return value", and that's only _one_ of the ways the functions can produce doc strings, I'd modify that to: `eldoc-documentation-compose': calls all the functions in the hook, and displays the doc strings that they produce... > > This doc string doesn't explain the use of the timer, it explains the > reason for its existence. It should also describe the use: > >> +(defvar eldoc--enthusiasm-curbing-timer nil >> + "Timer used by `eldoc-documentation-enthusiast' to avoid >blinking.") OK. > Last, but not least: the "async" part of the branch's name hints on > some advanced and extremely useful functionality that these changes > are supposed to allow, but I see no mention of that in NEWS and in the > manual bits. What did I miss? Not much, we talked about this. Will change NEWS according to what we discussed. Jo=C3=A3o