bug#43609: 28.0.50; eldoc-documentation-function [vs new eldoc-display-functions]

["João Távora" <joaotavora@gmail.com>]

[Lars, I'm CC'ing you specifcally since there's a patch to review at the
end.]

martin rudalics <rudalics@gmx.at> writes:

>> I'd like to help you, but I don't understand: are you updating Emacs to
>> master in all 50 of those drives?  Do you do this 50 times?  By hand?
>> Why can't you update your eldoc-tooltip.el in the process?
>
> Every year I experience around two or three crashes among my machines
> which run various operating systems ranging from Windows XP to Windows
> 10 and old stable to unstable Debian.  When a HD drive crashes, I try
> to recreate the prior state by plugging in an older disk or copy the
> contents of that older disk into a new one.  Thereafter, I usually
> update my Emacs repositories reusing my older libraries.  If I also have
> to update my libraries, I'm ending up in Augean stables.

I'm not sure I follow 100%, I'm just thinking that whatever process you
use to update Emacs in those machines you can also use to update
eldoc-tooltip.el.

> Then I fail to understand why my old code stopped working after your
> changes.  On the version of master I'm currently using here it's even
> documented in the Elisp manual as
>
> ‘eldoc-documentation-function’
>      This variable holds the function which is used to retrieve
>      documentation for the item at point from the functions in the hook
>      ‘eldoc-documentation-functions’.  By default,
>      ‘eldoc-documentation-function’ returns the first documentation
>      string produced by the ‘eldoc-documentation-functions’ hook.

And these things are true, still today, as far as I know. What I meant
is that the link between eldoc-documentation-function and
eldoc-documentation-functions was already established.  You were arguing
for some conceptual separation between these two variables and I noted
that they were already interconnected.

>> If "function definitions" were at stake, I would certainly agree with
>> you.  But they're not.
>
> Here 'elisp-eldoc-documentation-function' is a function defined in
> elisp-mode.el.  IIUC this function has gone now.

Ah right, then I misunderstood: you're talking about _that_ function.
That is indeed a function.  I thought you were talking about
eldoc-documentation-function, the variable, since that seems~ to have
been the original problem.  But what you're requesting seems to be the
functionally the martin() function I gave you earlier, right?

   (defun martin ()
     "CAUTION: Only works in default Emacs Lisp mode or modes with all-sync
   docstring generating functions.  If some functions calls the
   callback afterwards, that result is discarded."
   ...)

So you'd like it to be called elisp-eldoc-documentation-function, and
put in elisp-mode.el, right?  That _could_ be done, I guess, and I've
attached a patch at the end of this message.

But there's still something I don't understand: in your original
martin-tooltip.el library you didn't call this e-e-d-f function, did
you?  AFAIU, you did:

   (funcall eldoc-documentation-function)

or am I mistaken?  So you'd have to change your code anyway to now call
elisp-eldoc-documentation-function, right?  So, if you're going to
change it, why not change it to the new, better alternatives I have
presented?

Regardless, here's my take on '--': The presence of '--' clearly
specifies something to be an internal implementation detail. But that's
not the same as taking the absence of '--' as a sign that something is
an "external" function.  The '--' convention is relatively recent, and
programmers had been using internal details before the convention
existed.  This was one of them.

>> If you are going to update Emacs to master in N servers, you might as
>> well update your library in those N servers. If you're updating it by
>> hand, then this doesn't seem like a tremendous extra effort to expend.
>> If you're using a script, just put the library update in that script.  I
>> personally use Git to good effect for this: push once, pull many times.
>
> This is not something I do once to be done for ever.  It's something
> that I usually have to do in a troublesome situation where I have to
> recover from a previous crash and I'm trying to make some system run
> again.  I can't afford to plug in all sorts of hard disk drives in order
> to make them future-proof.

But isn't the problem that you've somehow built or placed a new version
of Emacs in those drives/servers/hosts where an incompatible
martin-tooltip.el lives?  I just don't understand why updating an Emacs
executable is somehow feasible in that setup but updating an Elisp
library that it depends on isn't.

>> Alternatively, and perhaps even better, you're invited to contribute
>> your library to Emacs (or GNU ELPA).  Then you'll just have to update
>> Emacs, using your preferred method.
>
> I'd still have to update each of my .emacs and install the respective
> calls for each version of Emacs I might use there.

I'm again confused: If you contribute your code to Emacs, then whenever
you update Emacs (which seems to be what you're concerned about) the
facilities you need will just be there.

João

As promised, a patch for you to review (and maybe Lars as well?)

diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index eed73f5791..f133635ec1 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -1411,6 +1411,30 @@ elisp--eldoc-last-data
       or argument string for functions.
   2 - `function' if function args, `variable' if variable documentation.")
 
+(defun elisp--documentation-one-liner ()
+  (let* (str
+         (callback (lambda (doc &rest plist)
+                     (setq str
+                           (format "%s: %s"
+                                   (propertize (prin1-to-string
+                                                (plist-get plist :thing))
+                                               'face (plist-get plist :face))
+                                   doc)))))
+    (or (progn (elisp-eldoc-var-docstring callback) str)
+        (progn (elisp-eldoc-funcall callback) str))))
+
+(defalias 'elisp-eldoc-documentation-function 'elisp--documentation-one-liner
+  "Return Elisp documentation for the thing at point as one-line string.
+This is meant as a backward compatibility aid to the \"old\"
+Elisp eldoc behaviour.  Consider variable docstrings and function
+signatures only, in this order.  If none applies, returns nil.
+Changes to `eldoc-documentation-functions' and
+`eldoc-documentation-strategy' are _not_ reflected here.  As such
+it is preferrable to use ElDoc's interfaces directly.")
+
+(make-obsolete 'elisp-eldoc-documentation-function
+               "use ElDoc's interfaces instead." "28.1")
+
 (defun elisp-eldoc-funcall (callback &rest _ignored)
   "Document function call at point.
 Intended for `eldoc-documentation-functions' (which see)."