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: Sun, 05 Jul 2020 13:03:48 +0100 Message-ID: <87o8oui2xn.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="24890"; 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 Sun Jul 05 14:04:10 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 1js3NS-0006NN-Gl for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 05 Jul 2020 14:04:10 +0200 Original-Received: from localhost ([::1]:45618 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1js3NR-0006WX-JQ for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 05 Jul 2020 08:04:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:35348) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1js3NK-0006RI-P0 for bug-gnu-emacs@gnu.org; Sun, 05 Jul 2020 08:04:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:48621) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1js3NK-0002w6-Fr for bug-gnu-emacs@gnu.org; Sun, 05 Jul 2020 08:04:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1js3NK-0000tV-C3 for bug-gnu-emacs@gnu.org; Sun, 05 Jul 2020 08:04: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: Sun, 05 Jul 2020 12:04:02 +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.15939506413430 (code B ref 41531); Sun, 05 Jul 2020 12:04:02 +0000 Original-Received: (at 41531) by debbugs.gnu.org; 5 Jul 2020 12:04:01 +0000 Original-Received: from localhost ([127.0.0.1]:60167 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1js3NI-0000tE-QE for submit@debbugs.gnu.org; Sun, 05 Jul 2020 08:04:01 -0400 Original-Received: from mail-wr1-f66.google.com ([209.85.221.66]:36801) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1js3NF-0000sy-S2 for 41531@debbugs.gnu.org; Sun, 05 Jul 2020 08:03:59 -0400 Original-Received: by mail-wr1-f66.google.com with SMTP id k6so37783141wrn.3 for <41531@debbugs.gnu.org>; Sun, 05 Jul 2020 05:03:57 -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=N+iaL/HybVXXg6rGMlteyVqNVTIbraO6UWN+cjt00R4=; b=mNEEL5T2yv9VBbuIV//fLz3ykYkbF/SZGepqH8L2SxL0cGraf+EZGq2DcfD4vvVONZ CzOseNW8PMXBI30wJhcvYLpTPzNqdx0YILTEL+H94OKQ9lFTpMbEfa5R77Ga2VuSngrl 2uYO3vdFr/F8l3uOve6j/DeRS4ynhpAZeNHH4YWs66oVVJZULm181wKFkAfNXOcuuSkK JzbvsSmkk1ZQ5vY5NXkRTsgiR4cWz+8utgqfRyoJWd68HRqVv5ymSvvGrorgk8K9MDL0 M8ixiVIJSciWcpLAoqQWy/sAlTulOVnBaIs8A5eeNmTGLrutDWDxDDhJMDXpSbxWIGv7 c6tA== 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=N+iaL/HybVXXg6rGMlteyVqNVTIbraO6UWN+cjt00R4=; b=Hw5qoxD3VuMTj23DMMK7MjT+ooUADej8pGG+SODS/ouPAyMOgHIfD915hPySlqdOv5 xXXx/FpPLNU4/HTlgapPXlVl966oB9HkytwMLJYR7RaCK3jiJ8c1pxPtpYdoPSt69AC3 U5/rKNDljBOnN+0lolPvGZ9+NNUXPuVuf5URz9vxoRfZH9iq8Oo/qUnex0V2tbWtuHww O5hN0ZCPk3Ka8uWqVYngIxFPVIRmqNMsRaqI7IZ0IsscCPhbJf2gEpd2x9FJ3ThjqVIO M/APb1u1Xgtoj7zGv7QIvylChSvRXyY8j3BXdzf4t2AvvVkbcRGjSOepPoV4NOuu/EQO Sucw== X-Gm-Message-State: AOAM530biVllWCsDr7QCPSzBt1cfKXOs681Ror/Arjwj/XJpeAR8u/vt 5vNFNn4xT3V6cL7i3NQyuyE= X-Google-Smtp-Source: ABdhPJz5z18M734ZWllWD4h/l6CJ2IrD4RdfcHNTB7CN67yaFiG/zTkPXuWQ+eOGK/g9ynzqw8xGqg== X-Received: by 2002:adf:e60a:: with SMTP id p10mr42289122wrm.181.1593950631904; Sun, 05 Jul 2020 05:03:51 -0700 (PDT) Original-Received: from krug (89-180-156-25.net.novis.pt. [89.180.156.25]) by smtp.gmail.com with ESMTPSA id z1sm20049371wru.30.2020.07.05.05.03.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 05 Jul 2020 05:03:50 -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:182734 Archived-At: Eli Zaretskii writes: >> -(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? Stuck with "1.1.0", because of the GNU ELPA criterion. But maybe the string could be "1.1.0-elpa" or something like that. > 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? Answered this already. > 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. Changed that paragraph to To call the CALLBACK function, the hook function must pass it an obligatory argument DOCSTRING, a string containing the documentation, followed by an optional list of keyword-value pairs of the form (:KEY VALUE :KEY2 VALUE2...). KEY can be: The situation is very similar to Flymake's flymake-diagnostic-functions. If you still find this docstring confusing, maybe I should copy that docstring's structure. > 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. I fixed all I could find, but is this a a hard rule? I like to break it once in a while: ;; We have to foo bar separately ... (foo bar) ;; ... because the bazness might be too quuxy. (if (quux) (foo baz)) I ended up not doing that this time, though. > The doc string of eldoc-documentation-compose doesn't say a word about > the function's argument. I fixed that by creating a helper eldoc--documentation-compose-1 that both eldoc-documentation-compose and eldoc-documentation-compose-eagerly call. I describe the arg in the helper. > This doc string doesn't explain the use of the timer, it explains the > reason for its existence. It should also describe the use: See the new version below. I think it is sufficient. Be aware this is an internal variable, we don't even let the user customize the time (we could though, but I think it's overcomplicating, for now). (defvar eldoc--enthusiasm-curbing-timer nil "Timer used by the `eldoc-documentation-enthusiast' strategy. When a doc string is encountered, it must endure a certain amount of time unchallenged until it is displayed to the user. This prevents blinking if a lower priority docstring comes in shortly before a higher priority one.") > 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? I reworded it, caught a bug, and mentioned eldoc-echo-area-use-multiline-p. Let me know it if you're missing anything. Jo=C3=A3o PS: Actually a proper section for Eldoc in the Emacs manual is probably missing, but I don't have time to work on it straight away. Or at least I think the fix should go in first.