Populate completions with metadata (#3226)

This makes it possible to override the cider completion style in completion-category-defaults or completion-category-overrides.

Author: toniz4

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### New features
 
+- [#3226](https://github.com/clojure-emacs/cider/pull/3226): Populate completions metadata, making it possible to change the style of completion via `completion-category-override` or `completion-category-defaults`.
 - [#2946](https://github.com/clojure-emacs/cider/issues/2946): Add custom var `cider-merge-sessions` to allow combining sessions in two different ways: Setting `cider-merge-sessions` to `'host` will merge all sessions associated with the same host within a project. Setting it to `'project` will combine all sessions of a project irrespective of their host.
 
 ## Changes

cider-completion.el

@@ -237,7 +237,20 @@ performed by `cider-annotate-completion-function'."
     (when (and (cider-connected-p)
                (not (or (cider-in-string-p) (cider-in-comment-p))))
       (list (car bounds) (cdr bounds)
-            (completion-table-dynamic #'cider-complete)
+            (lambda (prefix pred action)
+              ;; When the 'action is 'metadata, this lambda returns metadata about this
+              ;; capf, when action is (boundaries . suffix), it returns nil. With every
+              ;; other value of 'action (t, nil, or lambda), 'action is forwarded to
+              ;; (complete-with-action), together with (cider-complete), prefix and pred.
+              ;; And that function performs the completion based on those arguments.
+              ;;
+              ;; This api is better described in the section
+              ;; '21.6.7 Programmed Completion' of the elisp manual.
+              (cond ((eq action 'metadata) `(metadata (category . cider)))
+                    ((eq (car-safe action) 'boundaries) nil)
+                    (t (with-current-buffer (current-buffer)
+                         (complete-with-action action
+                                               (cider-complete prefix) prefix pred)))))
             :annotation-function #'cider-annotate-symbol
             :company-kind #'cider-company-symbol-kind
             :company-doc-buffer #'cider-create-doc-buffer

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

@@ -115,6 +115,18 @@ image::completion-annotations.png[Completion Annotations]
 TIP: Completion annotations can be disabled by setting
 `cider-annotate-completion-candidates` to `nil`.
 
+=== Changing the completion style
+
+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-defaults`, overriting the completion style of the CIDER
+complete at point function. The following snippet accomplishes that:
+
+[source,lisp]
+----
+(add-to-list 'completion-category-defaults '(cider (styles basic)))
+----
+
 === Updating stale classes and methods cache
 
 Sometimes, the completion fails to recognize new classes that came with