Working with 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).

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.

Most JDK distributions ship with a src.zip file (an archive with all base Java source files). If you have such archive present in your JDK, CIDER will automatically parse the source file when you query the documentation for a Java class (e.g. java.lang.Thread) or a method (e.g. java.lang.Thread/currentThread) and will display the properly formatted JavaDoc in the documentation buffer. You will also see better Eldoc documentation (minibuffer hints) for Java methods. If the source file are present, you are able to jump to class or method definition by pressing M-. on the class name or method name.

Furthermore, CIDER is able to parse JavaDoc source files and jump to definitions for third-party Java libraries if you have downloaded the special -sources.jar file for that library. See the next section on how to download source JARs.

Since version 1.17, CIDER is able to download the necessary source JAR file automatically when you either request the documentation for a Java class/method or when you jump to the definition of a Java class/method. In order for the sources to be downloaded, you need to enable custom variable cider-download-java-sources. When the download triggers, CIDER displays a minibuffer message about that. Fetching a single source JAR usually takes a few seconds. CIDER will make only one attempt to download the source JAR for a particular dependency per process — if it failed to download (usually, because the dependency doesn’t have a source JAR published to Maven), CIDER will not retry that until the next restart.

Alternatively, you can use enrich-classpath to download all source JARs used by your current project at once. This will incur longer startup time, but will not trigger individual JARs fetching at the runtime.

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:

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).

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

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.

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:

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:

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.

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