= 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 kbd:[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).

TIP: You can also use the keybinding kbd:[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.

NOTE: 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` (kbd:[C-c C-d j] or kbd:[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:

[source,lisp]
----
(setq browse-url-browser-function 'eww-browse-url)
----

== Searching in Docstrings

CIDER provides a handy alternative of `clojure.repl/find-doc` - `cider-apropos-documentation` (kbd:[C-c C-d f] or
kbd:[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` (kbd:[C-c C-d e] or kbd:[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 https://clojuredocs.org/[ClojureDocs service].
You've got two main ways of interacting with ClojureDocs:

* displaying the documentation in a dedicated buffer in Emacs via `cider-clojuredocs` (kbd:[C-c C-d C-c])
* opening the documentation in your default browser via `cider-clojuredocs-web` (kbd:[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.

TIP: Check out https://metaredux.com/posts/2019/12/14/exporting-clojuredocs-as-edn.html[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:[^}]+\\)}")
----

image::cider_see_also.gif[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`.

TIP: 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`
| kbd:[C-c C-d d] +
kbd:[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`
| kbd:[C-c C-d j] +
kbd:[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`
| kbd:[C-c C-d c] +
kbd:[C-c C-d C-c]
| Lookup symbol in ClojureDocs.

| `cider-clojuredocs-web`
| kbd:[C-c C-d w] +
kbd:[C-c C-d C-w]
| Open the ClojureDocs documentation for symbol in a web browser.

| `cider-apropos`
| kbd:[C-c C-d a] +
kbd:[C-c C-d C-a]
| Apropos search for functions/vars.

| `cider-apropos-documentation`
| kbd:[C-c C-d f] +
kbd:[C-c C-d C-f]
| Apropos search for documentation.

| `cider-apropos-documentation-select`
| kbd:[C-c C-d e] +
kbd:[C-c C-d C-e]
| Apropos search for documentation & select.
|===
