Function: eldoc--invoke-strategy

eldoc--invoke-strategy is a byte-compiled function defined in eldoc.el.gz.

Signature

(eldoc--invoke-strategy INTERACTIVE)

Documentation

Invoke eldoc-documentation-strategy function.

If INTERACTIVE is non-nil, the request came directly from a user command, otherwise it came from ElDoc's idle timer, eldoc-timer.

That function's job is to run the 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(var)/eldoc--make-callback(fun) protocol, using it to produce a callback argument to feed the functions that the user places in eldoc-documentation-functions. Whenever the strategy determines it has information to display to the user, this function passes responsibility to the functions in eldoc-display-functions.

Other third-party values of eldoc-documentation-strategy should not use eldoc--make-callback(var)/eldoc--make-callback(fun). They must find some alternate way to produce callbacks to feed to eldoc-documentation-functions and should endeavor to display the docstrings eventually produced, using eldoc-display-functions.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/eldoc.el.gz
(defun eldoc--invoke-strategy (interactive)
  "Invoke `eldoc-documentation-strategy' function.

If INTERACTIVE is non-nil, the request came directly from a user
command, otherwise it came from ElDoc's idle
timer, `eldoc-timer'.

That function's job is to run the `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 a callback
argument to feed the functions that the user places in
`eldoc-documentation-functions'.  Whenever the strategy
determines it has information to display to the user, this
function passes responsibility to the functions in
`eldoc-display-functions'.

Other third-party values of `eldoc-documentation-strategy' should
not use `eldoc--make-callback'.  They must find some alternate
way to produce callbacks to feed to
`eldoc-documentation-functions' and should endeavor to display
the docstrings eventually produced, using
`eldoc-display-functions'."
  (let* (;; How many callbacks have been created by the strategy
         ;; function and passed to elements of
         ;; `eldoc-documentation-functions'.
         (howmany 0)
         ;; How many calls to callbacks we're still waiting on.  Used
         ;; by `:patient'.
         (want 0)
         ;; The doc strings and corresponding options registered so
         ;; far.
         (docs-registered '())
         (orig-buffer (current-buffer)))
    (cl-labels
        ((register-doc
          (pos string plist origin)
          (when (and string (> (length string) 0))
            (push (cons pos (cons string `(:origin ,origin ,@plist)))
                  docs-registered)))
         (display-doc
           ()
           (when (buffer-live-p orig-buffer)
             (with-current-buffer orig-buffer
               (run-hook-with-args
                'eldoc-display-functions (mapcar #'cdr
                                                 (setq docs-registered
                                                       (sort docs-registered
                                                             (lambda (a b) (< (car a) (car b))))))
                interactive))))
         (make-callback
          (method origin)
          (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 origin))
                 (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 origin)
                 (when (zerop (cl-decf want)) (display-doc))
                 t))
              (:eager
               (lambda (string &rest plist)
                 (register-doc pos string plist origin)
                 (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, e-d-strategy is itself the
               ;; origin function, and we output immediately;
               (stringp res)
               (register-doc 0 res nil eldoc-documentation-strategy)
               (display-doc))
              (;; Old protocol: got nil, clear the echo area;
               (null res) (eldoc--message nil))
              (;; New protocol: trust callback will be called;
               t))))))