From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: =?UTF-8?Q?Jo=C3=A3o_?= =?UTF-8?Q?T=C3=A1vora?= Newsgroups: gmane.emacs.bugs Subject: bug#41531: 28.0.50; proper Eldoc async support Date: Wed, 03 Jun 2020 19:56:46 +0100 Message-ID: <87eeqwm101.fsf@gmail.com> References: <875zckuet9.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="102897"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 41531@debbugs.gnu.org To: Stefan Monnier , andreyk.mad@gmail.com, Dmitry Gutov , mvoteiza@udel.edu Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Jun 03 20:57: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 1jgYZZ-000Qcn-Q7 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 03 Jun 2020 20:57:09 +0200 Original-Received: from localhost ([::1]:39186 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jgYZY-0005nI-T3 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 03 Jun 2020 14:57:08 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:33276) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jgYZS-0005n8-7H for bug-gnu-emacs@gnu.org; Wed, 03 Jun 2020 14:57:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:33010) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jgYZR-0001YE-Uu for bug-gnu-emacs@gnu.org; Wed, 03 Jun 2020 14:57:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jgYZR-0007gh-Sz for bug-gnu-emacs@gnu.org; Wed, 03 Jun 2020 14:57:01 -0400 X-Loop: help-debbugs@gnu.org In-Reply-To: <875zckuet9.fsf@gmail.com> 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: Wed, 03 Jun 2020 18:57: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.159121061629539 (code B ref 41531); Wed, 03 Jun 2020 18:57:01 +0000 Original-Received: (at 41531) by debbugs.gnu.org; 3 Jun 2020 18:56:56 +0000 Original-Received: from localhost ([127.0.0.1]:44556 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jgYZM-0007gN-3C for submit@debbugs.gnu.org; Wed, 03 Jun 2020 14:56:56 -0400 Original-Received: from mail-wm1-f46.google.com ([209.85.128.46]:51523) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jgYZL-0007g6-2W for 41531@debbugs.gnu.org; Wed, 03 Jun 2020 14:56:55 -0400 Original-Received: by mail-wm1-f46.google.com with SMTP id u13so2936072wml.1 for <41531@debbugs.gnu.org>; Wed, 03 Jun 2020 11:56:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=Za6Xfh8TpSblVWbnvn+Ep7XieO81rpeTYCKxycWgDHY=; b=pot5BMIKcgObyqZNJ5b4lM6rJra6NLsMb2VEVYljDGaoAjBV10HBaR4SBWdKyzsj9Y HHkP1khwnWs6wgNqhM5JVO3tp2/LD+8pxw8TGgvfTvk6MIA7a1Mre+tp92HjYobi87jC wiZAJVUai6ASHzBrtuw5I6K/EOxAL5vA7WTRiQ00Kgiq0sQesl24MJS65+NhR0uTR2jG 2OLPvb22XQ7U7kpt9uCcErLB+a8WzbB1US0sHQocjR6UI+WLo7Xco2f8/YMRaU7gJHm8 i3u8PeCMhG42lNBWYDNViJgWR4MS7IUdykR9+ECowZwF0wRcaDt9isvPAk6mKSroicFo 1IfQ== 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:date:message-id:mime-version :content-transfer-encoding; bh=Za6Xfh8TpSblVWbnvn+Ep7XieO81rpeTYCKxycWgDHY=; b=tqadmucdo+dMwgry2o9HzQ89azytpOVuyHo2SicVws52nEcOchDyr9s82U7/+f+D+t YNsJhpUWAxHEig/vPX5ayMfdPsnMx1noZnH2yLAA0zWHkc9038uqQS03Rl0XJ8fSgKdQ RUiZn6HUZR2LGyH/cnFOhvoCs6IfYUSAugtXN4397Zcz/oNFkgNe01xASgJXruYLPjr6 /5TcuNWDrC4PmM9aAsmiY5t4KPSE1yYF4/9LS/0fcfTFNWNNqbzUy9uENxVk1LaR096H fnPqAO/xIUt2gWAWpq2xTL0h0cbSRPYlfY8IuQ6cDHLCWDpYeJVko0bzn1RRkxAdu/3C /wgQ== X-Gm-Message-State: AOAM532E4CIzrpqoaVBLRCktm+kLVH9NaXmJpHsgbBtBaCKD3nXIsHUQ SGc5DdEhxHIp8T8I0MC+EdZ40UaUyyY= X-Google-Smtp-Source: ABdhPJwH0iZTKw9fG2+cUPDpY57Idm42mlDvtfuf8h8PDwAM8DVQYcPprKjvL9vldd8NZkrr3HAUxQ== X-Received: by 2002:a1c:b155:: with SMTP id a82mr521305wmf.46.1591210608543; Wed, 03 Jun 2020 11:56:48 -0700 (PDT) Original-Received: from krug (89-180-148-153.net.novis.pt. [89.180.148.153]) by smtp.gmail.com with ESMTPSA id x8sm4606288wrs.43.2020.06.03.11.56.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 03 Jun 2020 11:56:47 -0700 (PDT) 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:181473 Archived-At: Hello again gang, As you might have seen in emacs-diffs, I have pushed a new scratch/eldoc-async branch to the Savannah repo. If you don't have this repo setup you can find the commits here in the meantime: https://github.com/emacs-mirror/emacs/tree/scratch/eldoc-async The code, which touches mostly lisp/emacs-lisp/eldoc.el contains the logical continuation of the improvements I started building two weeks ago. When applied, these improvements result in a substantial reduction of Eglot's documentation handling code. Yes, Andrii, that means all our hand-crafted, hard work of doc handling functions is soon gone, including the awkward eglot-put-doc-in-help-buffer, eglot-auto-display-help-buffer and the *eglot-help* buffer. Feels sad but also good, because deleted code is good code. And it's not in vain because your feedback and testing was fundamental here. And the good news is that the logic problems about blinking and giving priority to some docs is gone. There are 6 commits in total, that build on top of each other. In reverse order 10834f20ec * lisp/emacs-lisp/eldoc.el (Version): Bump to 1.1.0 fe93e5b9d5 Make eldoc-print-current-symbol-info a command 0612bb7ab5 Introduce eldoc-prefer-doc-buffer defcustom 40d45067ba Overhaul and handle (most of) eldoc-echo-area-use-multiline-= p in Eldoc itself 600b9c0a71 New eldoc-documentation-eager value for eldoc-documentation-= function cde8a6ab98 Better handle asynchronously produced eldoc docstrings And the new version of Eglot that makes uses of this eldoc is here. https://github.com/joaotavora/eglot/tree/scratch/work-with-new-eldoc It's important to note that Eldoc remains backward-compatible to all its previous users. In eldoc.el, things build on top of existing work, which includes the reasonably new eldoc-documentation-functions (plural). Earlier, I thought of this variable somewhat useless, but it's really not. In fact, it's exactly what Eglot, SLY and other modes are after. Even emacs-lisp-mode itself could benefit as it's often the case that one loses the documentation for a special variable just because one happen to be inside a function call, or vice versa. eldoc-documentation-functions allows us to split up these two competing sources of documentation, so thank you Mark, or whomever had this great idea. An orthogonal question is how to display the documentation we gather from multiple sources. That is handled by eldoc-documentation-function (singular), another variable I had underestimated. In my changes, I have added a third option to the two already existing ones. :type '(radio (function-item eldoc-documentation-default) (function-item eldoc-documentation-compose) (function-item eldoc-documentation-eager) (function :tag "Other function")) :version "28.1") Eglot defaults to eldoc-documentation-eager, which simulates its previous behavior. I suggest you see the docstring for each. Certainly we can have more strategies to combine documentation sources. Another important development is that now that the display is centralized, the formatiing can also be. Thus a big part of eldoc-echo-area-use-multiline-p can be easily honoured in eldoc.el itself. But the most complex changes pertain to async backends, such as Eglot's and some (but not all) of SLY. This is also covered. On this point, it is also extremely super-important to note that even though I have NOT used "futures" or "promises" in these patches, the very same things can be achieved with them, give or take some code here and there and some head-wrapping around different debugging techniques. I have NOT focused on the particular async programming technique: I just used the simplest and most commonly used in Emacs. Finally, there is a bit of future-proof unused API. Backends can call the documentation-reporting callback with keyword arguments, such as `:hint`. But they're not really used yet for anything yet. Some more sophisticated text formatting in the *eldoc doc* buffer, including renaming it like Eglot used to do to its *Eglot doc* buffer, is a possibility. Another possibility yet, also left unexplored, is for Flymake diagnostic messages at point to be reported as independent documentation sources. This is a frequent complain about Eglot. But in fact I think it should be Flymake-mode itself that adds some function to eldoc-documentation-functions. Jo=C3=A3o