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#43609: 28.0.50; eldoc-documentation-function Date: Thu, 01 Oct 2020 10:23:51 +0100 Message-ID: <871riijo48.fsf@gmail.com> References: <2e610c3f-6e5f-c7dd-af2e-aeb5e20d8664@gmx.at> <87r1qjjppu.fsf@gmail.com> <3fa6b315-7fc0-06ee-81e9-b68d164aec1b@gmx.at> <87a6x7jf9a.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="blaine.gmane.org:116.202.254.214"; logging-data="11663"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: 43609@debbugs.gnu.org To: martin rudalics Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Oct 01 11:25:29 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 1kNuq8-0002rH-L0 for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 01 Oct 2020 11:25:28 +0200 Original-Received: from localhost ([::1]:52480 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNuq6-0000qQ-0n for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 01 Oct 2020 05:25:26 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47500) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNupj-0000qI-8l for bug-gnu-emacs@gnu.org; Thu, 01 Oct 2020 05:25:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:50723) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kNupi-0001Qt-VW for bug-gnu-emacs@gnu.org; Thu, 01 Oct 2020 05:25:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kNupi-0000tI-Sy for bug-gnu-emacs@gnu.org; Thu, 01 Oct 2020 05:25: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: Thu, 01 Oct 2020 09:25:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 43609 X-GNU-PR-Package: emacs Original-Received: via spool by 43609-submit@debbugs.gnu.org id=B43609.16015442433336 (code B ref 43609); Thu, 01 Oct 2020 09:25:02 +0000 Original-Received: (at 43609) by debbugs.gnu.org; 1 Oct 2020 09:24:03 +0000 Original-Received: from localhost ([127.0.0.1]:34032 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kNuol-0000rj-36 for submit@debbugs.gnu.org; Thu, 01 Oct 2020 05:24:03 -0400 Original-Received: from mail-wm1-f41.google.com ([209.85.128.41]:56135) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kNuoj-0000rF-5K for 43609@debbugs.gnu.org; Thu, 01 Oct 2020 05:24:01 -0400 Original-Received: by mail-wm1-f41.google.com with SMTP id d4so2146652wmd.5 for <43609@debbugs.gnu.org>; Thu, 01 Oct 2020 02:24:01 -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=it/GiVCiLw8ZBVPfUjP069Viz7gu7KTiALrjnSEFugI=; b=eleC13//fYQ3DSSqGZAQiDMvPWeP5yWQkU8M9W09nnCjAQb5jZxbbN+kTz5LwN91L+ t2m/DHwUO7k4onoWmIoXkN1qfTst22+RzHYZ9WeXORuJJE+u0/bv25aRt5E+3PGZOay+ pXmSsz01ewg/NQjl+5YGbCZB3ZvLIaWSHFlzzDsdt4zVzciSC7M3qku1TfsSYDIsU28b uDoMyhqOReC3fIYSISI7Op1afdm5yA1yobIUjygrny5/yMZbvEsGJiITMduoMlwQe9LE zfthNGF/ZVdJbAbIpKmCGDEoeDwaijZdqdDp+DH3GDmccDIENG66clzVXNMYquuTQGyV JgRg== 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=it/GiVCiLw8ZBVPfUjP069Viz7gu7KTiALrjnSEFugI=; b=O/ULYn8PEv+GxK+Jn8t+q8px8nUcB64HcThqZXkCUfllbs7Hnbd3NWLMy3DbUHclRf L9wUpT24hgKFKO7hHujd61NnkNnloIXCMa7cGQZbrJwE1LPQQAjz0w2jOZdivQRx7v+/ QfEAJvz1jDrgQnYkHog4kmkpXdnKPdtHkVdS86DTPS3fvXS9oLBK2faOt0xvcSmBBo8u fyQu42wAUMBH5yF8bvfxRb6mbrl34A1LOVoswqKnkEfuXsFqDPofP1dIp21uGMhVUxVd LQZWnWZryo+kkRDvmXhfonle22J78d/QRUNfIy1wXeOi3IvtT3uXw90oDOx/sBSmWjEj dLwg== X-Gm-Message-State: AOAM531+6udfTVALnnkDWcEJaHQN4uxp4i5wvEtg+b02Loey2ekJngFA ehdE/JK02l9vuy5WggCmsXM4zDVZlnI= X-Google-Smtp-Source: ABdhPJzyR7CgMzdhzBmFnkxekAI4oh3YeZcfdKtLqFzJXNVgXTytssJv00IZwIsMQ2xCvD3FhhDWGw== X-Received: by 2002:a1c:4e0a:: with SMTP id g10mr7676581wmh.71.1601544234833; Thu, 01 Oct 2020 02:23:54 -0700 (PDT) Original-Received: from krug ([89.180.149.164]) by smtp.gmail.com with ESMTPSA id a15sm8757263wrn.3.2020.10.01.02.23.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 01 Oct 2020 02:23:54 -0700 (PDT) In-Reply-To: (martin rudalics's message of "Thu, 1 Oct 2020 10:40:26 +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:189481 Archived-At: martin rudalics writes: >> Maybe there are examples but I can't find a single example of a user >> variable ending in "-function" that's supposed to work like you describe >> or that explicitly advocates for it/against it. If libraries establish > We probably should be more defensive when writing doc-strings for such > variables. Maybe, but none of the docstrings of foo-bar-function variables I consulted explicitly say that you shouldn't call them directly and that that task is reserved for foo.el. But that's factually how they work. When foo.el intends for a function to be called by programs it usually provides 'foo-bar', the function, not 'foo-bar-function', the variable. >>> And as far as the former is concerned, I now cannot use even >>> 'elisp-eldoc-documentation-function' directly either because you >>> changed its return value too. >> >> I looked up uses of that function in the Emacs source tree and couldn't >> find any. Because of the reasoning explained above, I also expected >> Elisp mode to be its sole reasonable user. > > Agreed if you meant to say that eldoc-mode would be the sole reasonable > user of 'elisp-eldoc-documentation-function'. Yes, that's what I meant. >> But if you really insist , it's a very easy function to bring back I >> would say (in fact the function I gave you earlier is probably more >> useful generalization of it). > > I won't insist if I have something that substitutes it. And if you can > provide that something within eldoc.el, a simple cross reference from > the doc-string of 'eldoc-documentation-function(s)' would be enough. eldoc-documentation-function (singular) is now obsolete. If we do come up with such a synchronous, direct-call, get-me-the-docs function, it makes of course sense to document it somewhere. >>>> If you need a direct call, "give me the string" entry point to the >>>> eldoc.el library, one can be added. >>> >>> I think we should do that and provide it as compatibility layer for >>> people like me who need it. >> >> OK. Do you know very many of those? > > No. Do you know anyone who displays eldoc outside of the echo area? Indeed I do. Yuan Fu is working on a eldoc-box extension that displays documentation kind of a tooltip (a child frame I think it's called). https://github.com/casouri/eldoc-box/blob/master/eldoc-box.el Its implementation should also be considerably simplified by the upcoming eldoc-display-functions. But currently it uses eldoc-message-function which is not perfect for the async case. At any rate, it's more reliable than calling eldoc-documentation-function as you used to do. Additionally, eldoc.el itself can now display in a *eldoc for * buffer (much as you suggest below). In the latest branch, that is handled by a display function called eldoc-display-in-buffer. >>>> - Independent of your choice above, or do you want to get the return >>>> value as list of strings? Or as a single string, maybe concatenat= ed >>>> and propertized, exactly the way it is display[ed in the echo area= ]. >>> >>> I'd prefer a list of strings. >> >> What about a slightly more complex type? (but not much) > > No objections. > >> As of now, "enriched" docstrings can be seen as the association of a >> string with a number of properties, say the "thing" being documented, or >> the preferred "face" to do it in. Later on, a piece of documentation >> can have, for example, other optional meta-hints about it, such as the >> language or variations on itself for displaying under a very limiting >> context (such as the echo area), or very permissive context (such as a >> spacious Help-like buffer). > > I certainly would not mind a buffer (like *eldoc-latest*) that I could > consult to obtain the latest information eldoc caught about the symbol > at point of the selected window either. Maybe together with some status > indicator about how much of that information has been retrieved > already. I think your desired *eldoc-latest* buffer is the return value of the nullary eldoc-doc-buffer function. The buffer indeed has the "latest" documentation, but it, by itself, currently doesn't tell you how many of the eldoc-documentation-functions (plural) have yet to respond. That knowledge exists and is held by internal mechanisms of eldoc.el. We could expose it, but I prefer to avoid doing that unless a clear need arises (that isn't handled by anything else). >> So I think it the return value of such a function should thus be: >> >> ...a list (DOC ...) where DOC looks like (STRING :KEY VALUE :KEY2 >> VALUE2 ...). STRING is the a possibly propertized string >> containing the documentation's text and the remainder of DOC is >> an optional list of keyword-value pairs, described in >> `eldoc-documentation-functions'. >> >> This will make the return value of the desired function match the values >> given to eldoc-display-functions, which could come in advantageious. > > What, in a nutshell, would these 'eldoc-display-functions' be (sorry but > my master on this system is in an inconsistent state and I don't want to > resolve conflicts when pulling anything into it)? No problem, here's the full docstring of the variable: (defvar eldoc-display-functions '(eldoc-display-in-echo-area eldoc-display-in-buffer) "Hook of functions tasked with displaying ElDoc results. Each function is passed two arguments: DOCS and INTERACTIVE. DOCS is a list (DOC ...) where DOC looks like (STRING :KEY VALUE :KEY2 VALUE2 ...). STRING is the a possibly propertized string containing the documentation's text and the remainder of DOC is an optional list of keyword-value pairs, described in `eldoc-documentation-functions'. =20=20=20=20=20 INTERACTIVE says if the request to display doc strings came directly from the user or from ElDoc's automatic mechanisms'.") Mind you, this is only a draft. In particular, I wonder if point (and mouse position?) at the time when eldoc.el decided to automatically request documentation should also be passed in somehow. Maybe we could reuse the INTERACTIVE argument, which currently is non-nil only if user specifically pressed M-x eldoc on a thing to document. Yours sincerely, Jo=C3=A3o