Working with Documentation

Quick access to documentation is very important for productive development. That’s why CIDER puts a heavy emphasis on this and provides lot of documentation-related functionality.

Looking up Documentation

The most basic thing that you can do is go to some symbol and press C-c C-d C-d then. This open a documentation buffer containing all the relevant information about the thing referenced by the symbol (special form, var, Java method, etc).

You can also use the keybinding C-c C-d d. Most CIDER keymaps provide two versions of the same keybinding (with or without the final Control), as some people prefer to keep holding Control and some don’t.

Normally the command operates on the symbol at point. If invoked with a prefix argument, or no symbol is found at point, it will prompt for a symbol.

If using enrich-classpath, Java doc comments are available and rendered in the same way that Clojure docstrings are. They’re often much more handy than opening Javadoc in a browser. Starting from CIDER 1.8.0, the HTML-like language that they use is nicely rendered into syntax-colored strings, well-aligned tables, etc

JavaDoc

CIDER provides a quick access to the online Javadoc documentation via the command cider-javadoc (C-c C-d j or C-c C-d C-j), using your default browser.

Normally the command operates on the symbol at point. If invoked with a prefix argument, or no symbol is found at point, it will prompt for a symbol.

If you don’t want CIDER to use an external browser to display the JavaDoc you can use the built-in EWW browser instead like this:

(setq browse-url-browser-function 'eww-browse-url)

Searching in Docstrings

CIDER provides a handy alternative of clojure.repl/find-doc - cider-apropos-documentation (C-c C-d f or C-c C-d C-f). This allows you to search in the docstrings of all loaded vars with the results presented in Emacs’s apropos interface.

Alternatively you can use cider-apropos-documentation-select (C-c C-d e or C-c C-d C-e), which presents you the matching results as a list in the minibuffer, so you can quickly select what you need (especially if you’re using some package like ido or vertico).

ClojureDocs

CIDER provides integration with the popular ClojureDocs service. You’ve got two main ways of interacting with ClojureDocs:

  • displaying the documentation in a dedicated buffer in Emacs via cider-clojuredocs (C-c C-d C-c)

  • opening the documentation in your default browser via cider-clojuredocs-web (C-c C-d C-w)

The documentation is bundled with cider-nrepl as an EDN resource (or more precisely - with orchard, which is dependency of cider-nrepl) and it’s a snapshot of the ClojureDocs data. You can update it manually to the most recent version with M-x cider-clojuredocs-refresh-cache.

Keep in mind that the documentation in ClojureDocs is limited only to Clojure and a few Clojure Contrib libraries (e.g. core.async). ClojureScript is currently not supported there.

Check out this article if you’re curious about the internals of how CIDER interacts with ClojureDocs.

Generating Documentation Cross References

Sometimes in your documentation strings, you’d like to be able to point other programmers at different definitions. If you specify the name of a definition as a fully qualified symbol, or surround it in backticks (`...`) or Codox-style delimiters ([[...]]), CIDER will convert these references into live links when it displays the documentation string in the documentation buffer.

If the name is in another namespace, then you’ll have to include the fully qualified name in the docstring.

Example function with a docstring containing references:

(defn test-fn
  "Test function.
  Also see: clojure.core/map, clojure.core/reduce, `defn`.
  You can reference variables like `thor`, [[kubaru.data.zookeeper/yoda]].
  Also works with references to java interop forms, `java.lang.String/.length`."
  []
  (+ 1 1))

You can change the delimiters that CIDER uses to find references if you want to support other reference formats. Simply update the regexp in cider-doc-xref-regexp to match your preferred format. The first group of the regexp should always match the cross-reference name. For example, if you want to want to use Latex-style references (\ref{...}) instead, the regexp would be:

(setq cider-doc-xref-regexp "\\\\ref{\\(?1:[^}]+\\)}")
CIDER See Also

Displaying Documentation as Tooltips

By default CIDER will show the documentation for the symbol under the mouse in a tooltip (using an overlay) or your echo area. That’s controlled by the configuration setting cider-use-tooltips. You can disable this behavior by setting the variable to nil.

(setq cider-use-tooltips nil)

The tooltips will also be disabled if tooltip-mode is disabled or help-at-pt-display-when-idle is set to t.

Check out the documentation of help-at-pt-display-when-idle to understand better how the help-echo Emacs functionality works.

Keybindings

Command Keyboard shortcut Description

cider-doc

C-c C-d d
C-c C-d C-d

Display doc string for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol.

cider-javadoc

C-c C-d j
C-c C-d C-j

Display JavaDoc (in your default browser) for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol.

cider-clojuredocs

C-c C-d c
C-c C-d C-c

Lookup symbol in ClojureDocs.

cider-clojuredocs-web

C-c C-d w
C-c C-d C-w

Open the ClojureDocs documentation for symbol in a web browser.

cider-apropos

C-c C-d a
C-c C-d C-a

Apropos search for functions/vars.

cider-apropos-documentation

C-c C-d f
C-c C-d C-f

Apropos search for documentation.

cider-apropos-documentation-select

C-c C-d e
C-c C-d C-e

Apropos search for documentation & select.