= ElDoc

Eldoc is a buffer-local minor mode that helps with looking up Lisp
documentation. When it is enabled, the echo area displays some useful
information whenever there is a Lisp function or variable at point;
for a function, it shows the argument list, and for a variable it
shows the first line of the variable's documentation string.

CIDER provides a Clojure backend for ElDoc that works out-of-the box, as
long as `eldoc-mode` is enabled.

image::eldoc.png[Eldoc]

== Enabling ElDoc

`global-eldoc-mode` is enabled by default in Emacs 25.1, so you don't really have
to do anything to enable it.

It will work in both source and REPL buffers.

== Configuring ElDoc

=== Displaying ElDoc for the Symbol at Point

Typically you'd see the eldoc for the containing function/macro/special form (with
respect to your cursor's position).

CIDER also would show the eldoc for the symbol at point. So in `+(map inc ...)+`
when the cursor is over `inc` its eldoc would be displayed. You can turn off this
behavior by:

[source,lisp]
----
(setq cider-eldoc-display-for-symbol-at-point nil)
----

=== Dealing with Long ElDoc

CIDER respects the value of `eldoc-echo-area-use-multiline-p` when
displaying documentation in the minibuffer. You can customize this variable to change
its behavior.

|===
| eldoc-echo-area-use-multiline-p | Behavior

| `t`
| Never attempt to truncate messages. Complete symbol name and function arglist or variable documentation will be displayed even if echo area must be resized to fit.

| `nil`
| Messages are always truncated to fit in a single line of display in the echo area.

| `truncate-sym-name-if-fit` or anything non-nil
| Symbol name may be truncated if it will enable the function arglist or documentation string to fit on a single line. Otherwise, behavior is just like `t` case.
|===

=== Context-dependent ElDoc

CIDER will try to add expected function arguments based on the current context
(for example for the `datomic.api/q` function where it will show the expected
inputs of the query at point), if the variable `cider-eldoc-display-context-dependent-info`
is non-nil:

[source,lisp]
----
(setq cider-eldoc-display-context-dependent-info t)
----

=== Disable CIDER's ElDoc Function

If you're using CIDER alongside `clojure-lsp` you might prefer to use `clojure-lsp` for ElDoc. This means you'll have to remove CIDER's ElDoc function from the list of registered ElDoc functions:

[source,lisp]
----
(remove-hook 'eldoc-documentation-functions #'cider-eldoc)
----

TIP: If you're dealing with a lot of packages providing some ElDoc integration
it's a good idea to learn about
https://www.masteringemacs.org/article/seamlessly-merge-multiple-documentation-sources-eldoc[merging
multiple documentation sources with ElDoc]. In brief - Emacs 28 added support
for multiple documentation backends. Now you can read error messages from your
linter or compiler *and* see code documentation at the same time. Cool stuff!
