mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-14 09:39:42 +00:00
Code Issues Releases Activity

; Reword bits of ElDoc internal documentation

Browse Source 
* lisp/emacs-lisp/eldoc.el (eldoc--invoke-strategy): Rewrite docstring.
(eldoc--invoke-strategy): Fix formatting and rewrite comments
This commit is contained in:
João Távora 2020-07-18 23:50:00 +01:00
parent 8d05f21946
commit 4a7ecaaee0
1 changed files with 65 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
lisp/emacs-lisp/eldoc.el
View File

@ -664,75 +664,75 @@ have the following values:
"Invoke `eldoc-documentation-strategy' function.
That function's job is to run the `eldoc-documentation-functions'
special hook, using the `run-hook' family of functions. The way
we invoke it here happens in a way strategy function can itself
call `eldoc--make-callback' to produce values to give to the
elements of the special hook `eldoc-documentation-functions'.
special hook, using the `run-hook' family of functions. ElDoc's
built-in strategy functions play along with the
`eldoc--make-callback' protocol, using it to produce callback to
feed to the functgions of `eldoc-documentation-functions'.
For each element of `eldoc-documentation-functions' invoked a
corresponding call to `eldoc--make-callback' must be made. See
docstring of `eldoc--make-callback' for the types of callback
that can be produced.
If the strategy function does not use `eldoc--make-callback', it
must find some alternate way to produce callbacks to feed to
`eldoc-documentation-function', and those callbacks should
endeavour to display the docstrings given to them."
(let* (;; how many docstrings callbaks have been
Other third-party strategy functions do not use
`eldoc--make-callback'. They must find some alternate way to
produce callbacks to feed to `eldoc-documentation-function' and
should endeavour to display the docstrings eventually produced."
(let* (;; How many callbacks have been created by the strategy
;; fucntion and passed to elements of
;; `eldoc-documentation-functions'.
(howmany 0)
;; how many calls to callbacks we're waiting on. Used by
;; `:patient'.
;; How many calls to callbacks we're still waiting on. Used
;; by `:patient'.
(want 0)
;; how many doc strings and corresponding options have been
;; registered it.
;; The doc strings and corresponding options registered so
;; far.
(docs-registered '()))
(cl-labels
((register-doc (pos string plist)
(when (and string (> (length string) 0))
(push (cons pos (cons string plist)) docs-registered)))
(display-doc ()
(eldoc--handle-docs
(mapcar #'cdr
(setq docs-registered
(sort docs-registered
(lambda (a b) (< (car a) (car b))))))))
(make-callback (method)
(let ((pos (prog1 howmany (cl-incf howmany))))
(cl-ecase method
(:enthusiast
(lambda (string &rest plist)
(when (and string (cl-loop for (p) in docs-registered
never (< p pos)))
(setq docs-registered '())
(register-doc pos string plist)
(when (and (timerp eldoc--enthusiasm-curbing-timer)
(memq eldoc--enthusiasm-curbing-timer
timer-list))
(cancel-timer eldoc--enthusiasm-curbing-timer))
(setq eldoc--enthusiasm-curbing-timer
(run-at-time (unless (zerop pos) 0.3)
nil #'display-doc)))
t))
(:patient
(cl-incf want)
(lambda (string &rest plist)
(register-doc pos string plist)
(when (zerop (cl-decf want)) (display-doc))
t))
(:eager
(lambda (string &rest plist)
(register-doc pos string plist)
(display-doc)
t))))))
(let* ((eldoc--make-callback #'make-callback)
(res (funcall eldoc-documentation-strategy)))
;; Observe the old and the new protocol:
(cond (;; Old protocol: got string, output immediately;
(stringp res) (register-doc 0 res nil) (display-doc))
(;; Old protocol: got nil, clear the echo area;
(null res) (eldoc--message nil))
(;; New protocol: trust callback will be called;
t))))))
(cl-labels
((register-doc
(pos string plist)
(when (and string (> (length string) 0))
(push (cons pos (cons string plist)) docs-registered)))
(display-doc
()
(eldoc--handle-docs
(mapcar #'cdr
(setq docs-registered
(sort docs-registered
(lambda (a b) (< (car a) (car b))))))))
(make-callback
(method)
(let ((pos (prog1 howmany (cl-incf howmany))))
(cl-ecase method
(:enthusiast
(lambda (string &rest plist)
(when (and string (cl-loop for (p) in docs-registered
never (< p pos)))
(setq docs-registered '())
(register-doc pos string plist)
(when (and (timerp eldoc--enthusiasm-curbing-timer)
(memq eldoc--enthusiasm-curbing-timer
timer-list))
(cancel-timer eldoc--enthusiasm-curbing-timer))
(setq eldoc--enthusiasm-curbing-timer
(run-at-time (unless (zerop pos) 0.3)
nil #'display-doc)))
t))
(:patient
(cl-incf want)
(lambda (string &rest plist)
(register-doc pos string plist)
(when (zerop (cl-decf want)) (display-doc))
t))
(:eager
(lambda (string &rest plist)
(register-doc pos string plist)
(display-doc)
t))))))
(let* ((eldoc--make-callback #'make-callback)
(res (funcall eldoc-documentation-strategy)))
;; Observe the old and the new protocol:
(cond (;; Old protocol: got string, output immediately;
(stringp res) (register-doc 0 res nil) (display-doc))
(;; Old protocol: got nil, clear the echo area;
(null res) (eldoc--message nil))
(;; New protocol: trust callback will be called;
t))))))
(defun eldoc-print-current-symbol-info (&optional interactive)
"Document thing at point."