Add sensible category overrides for cider (#3504)

This possibility was enabled by #3226

It can be seen in use in SystemCrafters/crafted-emacs#241 or https://clojurians.slack.com/archives/C0617A8PQ/p1696684010392119?thread_ts=1696618691.247989&cid=C0617A8PQ|

It provides a better default experience for those using orderless or other newer styles.

CHANGELOG.md

@@ -48,6 +48,8 @@
 
 ### Changes
 
+- Ensure that `cider` completion isn't used with completion styles that are currently unsupported (`flex` `initials` `partial-completion`, `orderless`, etc).
+  - This restores completions for users that favor those styles - otherwise the would see bad or no completions.
 - Improve support for multiple forms in the same line by replacing `beginning-of-defun` fn.
 - [#3390](https://github.com/clojure-emacs/cider/issues/3390): Enhance `cider-connect` to show all nREPLs available ports, instead of only Leiningen ones.
 - [#3408](https://github.com/clojure-emacs/cider/issues/3408): `cider-connect`: check `.nrepl-port`-like files for liveness, hiding them if they don't reflect an active port.

cider-completion.el

@@ -249,6 +249,11 @@ in the buffer."
                cider-company-unfiltered-candidates
                "CIDER backend-driven completion style."))
 
+;; Currently CIDER completions only work for `basic`, and not `initials`, `partial-completion`, `orderless`, etc.
+;; So we ensure that those other styles aren't used with CIDER, otherwise one would see bad or no completions at all.
+;; This `add-to-list` call can be removed once we implement the other completion styles.
+(add-to-list 'completion-category-overrides '(cider (styles basic flex)))
+
 (defun cider-company-enable-fuzzy-completion ()
   "Enable backend-driven fuzzy completion in the current buffer."
   (setq-local completion-styles '(cider)))

doc/modules/ROOT/pages/usage/code_completion.adoc

@@ -35,6 +35,21 @@ Normally kbd:[TAB] only indents, but now it will also do completion if the code
 is already properly indented.
 ====
 
+== Completion styles
+
+CIDER defines (via the `completion-styles-alist` Elisp variable) a completion category named `cider`.
+
+The `cider` completion category currently only supports `basic` and `flex` completion styles (and not `partial-completion`, `orderless`, etc).
+
+CIDER declares so in this fashion:
+
+[source,lisp]
+----
+(add-to-list 'completion-category-overrides '(cider (styles basic flex)))
+---
+
+Note that `flex` will only work if you also enabled xref:usage/code_completion.adoc#fuzzy-candidate-matching[fuzzy candidate matching].
+
 == Auto-completion
 
 While the standard Emacs tooling works just fine, we suggest that