branch: elpa/cider
commit 2d86379210e81d02db460aca59ca877668aca0b6
Author: Oleksandr Yakushev <a...@bytopia.org>
Commit: Oleksandr Yakushev <a...@bytopia.org>
[docs] Update user manual about completion
---
doc/modules/ROOT/pages/usage/code_completion.adoc | 86 +++++++++++------------
1 file changed, 41 insertions(+), 45 deletions(-)
diff --git a/doc/modules/ROOT/pages/usage/code_completion.adoc
b/doc/modules/ROOT/pages/usage/code_completion.adoc
index e354b587fa..68d8379bde 100644
--- a/doc/modules/ROOT/pages/usage/code_completion.adoc
+++ b/doc/modules/ROOT/pages/usage/code_completion.adoc
@@ -35,32 +35,6 @@ Normally kbd:[TAB] only indents, but now it will also do
completion if the code
is already properly indented.
====
-== Completion styles
-
-CIDER defines a specialized completion category through the
`cider-complete-at-point` function,
-added to `completion-at-point-functions`, establishing a dedicated completion
category named
-`cider`.
-
-The CIDER completion at point function supports most completion styles,
-including `partial-completion`, `orderless` and `flex`. It also supports a
-custom completion style that is confusingly named `cider` too. Activating it
-provides a richer set of completion candidates (see
-xref:usage/code_completion.adoc#fuzzy-candidate-matching[fuzzy candidate
-matching]).
-
-Sometimes the user may want to use a different completion style just for the
CIDER
-complete at point function. That can be achieved by setting
-`completion-category-overrides`, overwriting the completion style of the CIDER
-complete at point function. The following snippet accomplishes that:
-
-[source,lisp]
-----
-(add-to-list 'completion-category-overrides '(cider (styles basic)))
-----
-
-This specifies that the `cider` completion category should employ the basic
completion style by
-default.
-
== Auto-completion
While the standard Emacs tooling works just fine, we suggest that
@@ -139,31 +113,30 @@ without needing to hit an extra key, please customize:
(custom-set-variables '(company-auto-update-doc t))
----
-=== Fuzzy candidate matching
+=== Rich candidate matching
+
+Starting with version 1.18, CIDER by default enables a custom completion style
+that provides richer and more useful candidate matching, for example:
-By default, CIDER will use the completion styles defined in
-`completion-styles`, the defaults being `(basic partial-completion
-emacs22)` since Emacs 23. For a better description of how those
-completion styles operates, refer to the official Emacs manual on
-https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion-Styles.html[how
completion alternatives are chosen].
+- Long vars that contain dashes by first characters of individual parts, e.g.
+ `mi` or `mai` complete to `map-indexed`.
+- Namespaces by first characters of parts, e.g. `cji` completes to
+ `clojure.java.io`.
+- Not imported classnames by their short name prefixes, e.g. `BiFun` completes
+ to `java.util.function.BiFunction`.
+
+You can learn all completion scenarios and features
+https://github.com/alexander-yakushev/compliment/wiki/Examples[here].
-CIDER provides a function to enable the `cider` completion style for
CIDER-specific
-completions. If you wish to enable that, you can add this to your config:
+If you only want to receive standard prefix-restricted completions (where the
+candidate must contain the prefix at the beginning verbatim), you can disable
+this feature by adding this to your config:
[source,lisp]
----
-(cider-enable-cider-completion-style)
+(cider-enable-cider-completion-style -1)
----
-This adds the `cider` completion style for CIDER buffers.
-
-Now, `company-mode` (and other completion packages like `corfu`) will
-accept certain fuzziness when matching candidates against the
-prefix. For example, typing `mi` will show you `map-indexed` as one of
-the possible completion candidates and `cji` will complete to
-`clojure.java.io`. Different completion examples are shown
-https://github.com/alexander-yakushev/compliment/wiki/Examples[here].
-
=== Completion annotations
Completion candidates will be annotated by default with an abbreviation
@@ -178,6 +151,29 @@ image::completion-annotations.png[Completion Annotations]
TIP: Completion annotations can be disabled by setting
`cider-annotate-completion-candidates` to `nil`.
+=== Completion styles
+
+The CIDER completion at point function supports most completion styles,
+including `partial-completion`, `orderless`, `flex`, and its own custom
+completion style named `cider`. The latter is enabled by default. Sometimes the
+user may want to use a different completion style for the CIDER complete at
+point function. That can be achieved by setting
`completion-category-overrides`,
+overwriting the completion style of the CIDER complete at point function. The
+following snippet accomplishes that:
+
+[source,lisp]
+----
+(add-to-list 'completion-category-overrides '(cider (styles basic)))
+----
+
+For a better description of how those completion styles operates, refer to the
+official Emacs manual on
+https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion-Styles.html[how
+completion alternatives are chosen].
+
+This specifies that the `cider` completion category should employ the basic
completion style by
+default.
+
=== Notes on class disambiguation
Sometimes, the completion user experience may be interrupted by a
`completing-read`
@@ -212,6 +208,6 @@ NOTE: You don't really need to know any of this if you're
using only `cider-jack
The bulk of the code completion logic resides in `cider-nrepl`
https://github.com/clojure-emacs/cider-nrepl/blob/master/src/cider/nrepl/middleware/complete.clj[completion
middleware]. Internally it delegates to `compliment` for the Clojure
completion and `clj-suitable` for the ClojureScript completion.
-Starting with nREPL 0.8, there's also a built-in `completions` nREPL op that
CIDER will fallback to, in the absence of `cider-nrepl`. Its API is similar to
that of the `complete` op in `cider-nrepl` and it can be configured to use
different completion functions. The built-in op currently supports only
Clojure. See the https://nrepl.org/nrepl/usage/misc.html#code-completion[nREPL
docs] for more details.
+nREPL also has a built-in `completions` op that CIDER will fallback to, in the
absence of `cider-nrepl`. Its API is similar to that of the `complete` op in
`cider-nrepl` and it can be configured to use different completion functions.
The built-in op currently supports only Clojure. See the
https://nrepl.org/nrepl/usage/misc.html#code-completion[nREPL docs] for more
details.
Basically, you'll get great code completion in the presence of `cider-nrepl`
and basic completion otherwise.
