Introduce Java doc comment rendering (#3472)

Author: vemv

.dir-locals.el

@@ -8,14 +8,10 @@
   (fill-column . 80)
   (sentence-end-double-space . t)
   (emacs-lisp-docstring-fill-column . 75)
-  ;; slightly increase the maximum (applies to checkdoc and the byte compiler alike)
-  (byte-compile-docstring-max-column 100)
   (checkdoc-symbol-words . ("top-level" "major-mode" "macroexpand-all" "print-level" "print-length"))
   (checkdoc-package-keywords-flag)
   (checkdoc-arguments-in-order-flag)
   (checkdoc-verb-check-experimental-flag)
-  ;; allow commas to indicate that the first sentence continues, which enables longer first sentences
-  (checkdoc-permit-comma-termination-flag t)
   (elisp-lint-indent-specs . ((if-let* . 2)
                               (when-let* . 1)
                               (let* . defun)

.github/workflows/test.yml

@@ -23,6 +23,7 @@ jobs:
       matrix:
         os: [macos-latest, ubuntu-latest, windows-latest]
         emacs_version: ['26.3', '27.2', '28.2', '29.1']
+        java_version: ['11', '17']
 
     steps:
     - name: Set up Emacs
@@ -67,7 +68,7 @@ jobs:
       with:
         distribution: 'temurin'
         # shadow requires java 11
-        java-version: 11
+        java-version: ${{matrix.java_version}}
 
     - name: Install Clojure Tools
       # Use SHA until
@@ -91,3 +92,11 @@ jobs:
         # be GH connectivity runner issues. We attempt to address this
         # problem by rerunning the tests more than once.
         eldev -p -dtTC test --test-type integration || eldev -p -dtTC test --test-type integration
+        
+    - name: Run tests that need enrich-classpath
+      if: "!startsWith(matrix.os, 'windows')"
+      run: |
+        cd dev; ../clojure.sh clojure -M:gen; cd -
+        wc -l test/File.edn
+        eldev -p -dtTC test --test-type enrich || eldev -p -dtTC test --test-type enrich
+        

.gitignore

@@ -16,3 +16,4 @@ cider-pkg.el
 cider-refcard.aux
 cider-refcard.log
 doc/auto/
+test/*.edn

Eldev

@@ -11,25 +11,32 @@
 (eldev-add-loading-roots 'test "test/utils")
 (eldev-add-extra-dependencies 'runtime '(:package logview :optional t))
 
+;; slightly increase the maximum (applies to checkdoc and the byte compiler alike)
+(setq byte-compile-docstring-max-column 100)
+
+;; allow commas to indicate that the first sentence continues, which enables longer first sentences
+(setq checkdoc-permit-comma-termination-flag t)
+
 (defvar cider-test-type 'main)
 (setf eldev-standard-excludes `(:or ,eldev-standard-excludes
                                     ;; Avoid including files in test "projects".
                                     (eldev-pcase-exhaustive cider-test-type
                                                             (`main        "./test/*/")
                                                             (`integration '("./test/"   "!./test/integration"))
+                                                            (`enrich      '("./test/"   "!./test/enrich"))
                                                             (`all         '("./test/*/" "!./test/integration")))
                                     "test/integration/projects"
                                     ;; This file is _supposed_ to be excluded
                                     ;; from automated testing.
                                     "test/cider-tests--no-auto.el"))
 
 (eldev-defoption cider-test-selection (type)
-  "Select tests to run; type can be `main', `integration' or `all'"
+  "Select tests to run; type can be `main', `integration', `enrich' or `all'"
   :options        (-T --test-type)
   :for-command    test
   :value          TYPE
   :default-value  cider-test-type
-  (unless (memq (intern type) '(main integration all))
+  (unless (memq (intern type) '(main integration enrich all))
     (signal 'eldev-wrong-option-usage `("unknown test type `%s'" ,type)))
   (setf cider-test-type (intern type)))
 

Makefile

@@ -19,9 +19,15 @@ lint: clean
 compile: clean
 	 eldev -dtT compile --warnings-as-errors
 
-test-all: clean
+test/File.edn:
+	cd dev; ../clojure.sh clojure -M:gen
+
+test-all: clean test/File.edn
 	eldev -dtT -p test --test-type all
 
+test-enrich: clean test/File.edn
+	eldev -dtT -p test --test-type enrich
+
 test-integration: clean
 	eldev -dtT -p test --test-type integration
 

cider-client.el

@@ -34,6 +34,7 @@
 (require 'spinner)
 
 (require 'cider-connection)
+(require 'cider-completion-context)
 (require 'cider-common)
 (require 'cider-util)
 (require 'nrepl-client)
@@ -520,15 +521,15 @@ When multiple matching vars are returned you'll be prompted to select one,
 unless ALL is truthy."
   (when (and var (not (string= var "")))
     (let ((var-info (cond
-                     ((cider-nrepl-op-supported-p "info") (cider-sync-request:info var))
+                     ((cider-nrepl-op-supported-p "info") (cider-sync-request:info var nil nil (cider-completion-get-context t)))
                      ((cider-nrepl-op-supported-p "lookup") (cider-sync-request:lookup var))
                      (t (cider-fallback-eval:info var)))))
       (if all var-info (cider--var-choice var-info)))))
 
 (defun cider-member-info (class member)
   "Return the CLASS MEMBER's info as an alist with list cdrs."
   (when (and class member)
-    (cider-sync-request:info nil class member)))
+    (cider-sync-request:info nil class member (cider-completion-get-context t))))
 
 
 ;;; Requests
@@ -646,13 +647,14 @@ CONTEXT represents a completion context for compliment."
                                  nil
                                  'abort-on-input))
 
-(defun cider-sync-request:info (symbol &optional class member)
-  "Send \"info\" op with parameters SYMBOL or CLASS and MEMBER."
+(defun cider-sync-request:info (symbol &optional class member context)
+  "Send \"info\" op with parameters SYMBOL or CLASS and MEMBER, honor CONTEXT."
   (let ((var-info (thread-first `("op" "info"
                                   "ns" ,(cider-current-ns)
                                   ,@(when symbol `("sym" ,symbol))
                                   ,@(when class `("class" ,class))
-                                  ,@(when member `("member" ,member)))
+                                  ,@(when member `("member" ,member))
+                                  ,@(when context `("context" ,context)))
                                 (cider-nrepl-send-sync-request (cider-current-repl)))))
     (if (member "no-info" (nrepl-dict-get var-info "status"))
         nil
@@ -669,13 +671,14 @@ CONTEXT represents a completion context for compliment."
         nil
       (nrepl-dict-get var-info "info"))))
 
-(defun cider-sync-request:eldoc (symbol &optional class member)
-  "Send \"eldoc\" op with parameters SYMBOL or CLASS and MEMBER."
+(defun cider-sync-request:eldoc (symbol &optional class member context)
+  "Send \"eldoc\" op with parameters SYMBOL or CLASS and MEMBER, honor CONTEXT."
   (when-let* ((eldoc (thread-first `("op" "eldoc"
                                      "ns" ,(cider-current-ns)
                                      ,@(when symbol `("sym" ,symbol))
                                      ,@(when class `("class" ,class))
-                                     ,@(when member `("member" ,member)))
+                                     ,@(when member `("member" ,member))
+                                     ,@(when context `("context" ,context)))
                                    (cider-nrepl-send-sync-request (cider-current-repl)
                                                                   'abort-on-input))))
     (if (member "no-eldoc" (nrepl-dict-get eldoc "status"))

cider-completion-context.el

@@ -0,0 +1,122 @@
+;;; cider-completion-context.el --- Context parsing -*- lexical-binding: t -*-
+
+;; Copyright © 2013-2023 Bozhidar Batsov, Artur Malabarba and CIDER contributors
+;;
+;; Author: Bozhidar Batsov <[email protected]>
+;;         Artur Malabarba <[email protected]>
+
+;; This program is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;; This file is not part of GNU Emacs.
+
+;;; Commentary:
+
+;; Context-parsing utilities.  Extracted from cider-completion.el.
+
+;;; Code:
+
+(defcustom cider-completion-use-context t
+  "When true, uses context at point to improve completion suggestions."
+  :type 'boolean
+  :group 'cider
+  :package-version '(cider . "0.7.0"))
+
+(defun cider-completion--bounds-of-non-string-symbol-at-point ()
+  "Returns the bounds of the symbol at point, unless it's inside a string."
+  (let ((sap (symbol-at-point)))
+    (when (and sap (not (nth 3 (syntax-ppss))))
+      (bounds-of-thing-at-point 'symbol))))
+
+(defun cider-completion-symbol-start-pos ()
+  "Find the starting position of the symbol at point, unless inside a string."
+  (car (cider-completion--bounds-of-non-string-symbol-at-point)))
+
+(defun cider-completion-symbol-end-pos ()
+  "Find the end position of the symbol at point, unless inside a string."
+  (cdr (cider-completion--bounds-of-non-string-symbol-at-point)))
+
+(defun cider-completion-get-info-context-at-point ()
+  "Extract a context at point that is suitable for eldoc and info ops.
+Note that this context is slightly different than that of
+`cider-completion-get-context-at-point': this one does not include
+the current symbol at point."
+  (when (save-excursion
+          (condition-case _
+              (progn
+                (up-list)
+                (check-parens)
+                t)
+            (scan-error nil)
+            (user-error nil)))
+    (save-excursion
+      (let* ((pref-start (cider-completion-symbol-start-pos))
+             (context (cider-defun-at-point))
+             (end (cider-completion-symbol-end-pos))
+             (_ (beginning-of-defun-raw))
+             (expr-start (point))
+             (_ (if (derived-mode-p 'cider-repl-mode)
+                    (goto-char (point-max))
+                  (end-of-defun)))
+             (expr-end (point)))
+        (string-remove-suffix "\n"
+                              (concat (when pref-start (substring context 0 (- pref-start expr-start)))
+                                      "__prefix__"
+                                      (substring context (- (- expr-end end)))))))))
+
+(defun cider-completion-get-context-at-point ()
+  "Extract the context at point.
+If point is not inside the list, returns nil; otherwise return \"top-level\"
+form, with symbol at point replaced by __prefix__."
+  (when (save-excursion
+          (condition-case _
+              (progn
+                (up-list)
+                (check-parens)
+                t)
+            (scan-error nil)
+            (user-error nil)))
+    (save-excursion
+      (let* ((pref-end (point))
+             (pref-start (cider-completion-symbol-start-pos))
+             (context (cider-defun-at-point))
+             (_ (beginning-of-defun-raw))
+             (expr-start (point)))
+        (concat (when pref-start (substring context 0 (- pref-start expr-start)))
+                "__prefix__"
+                (substring context (- pref-end expr-start)))))))
+
+(defvar cider-completion-last-context nil)
+
+(defun cider-completion-get-context (&optional info)
+  "Extract context depending (maybe of INFO type).
+
+Output depends on `cider-completion-use-context' and the current major mode."
+  (let ((context (if cider-completion-use-context
+                     ;; We use ignore-errors here since grabbing the context
+                     ;; might fail because of unbalanced parens, or other
+                     ;; technical reasons, yet we don't want to lose all
+                     ;; completions and throw error to user because of that.
+                     (or (ignore-errors
+                           (if info
+                               (cider-completion-get-info-context-at-point)
+                             (cider-completion-get-context-at-point)))
+                         "nil")
+                   "nil")))
+    (if (string= cider-completion-last-context context)
+        ":same"
+      (setq cider-completion-last-context context)
+      context)))
+
+(provide 'cider-completion-context)
+;;; cider-completion-context.el ends here

cider-completion.el

@@ -31,16 +31,12 @@
 
 (require 'cider-client)
 (require 'cider-common)
+(require 'cider-completion-context)
 (require 'cider-doc)
+(require 'cider-docstring)
 (require 'cider-eldoc)
 (require 'nrepl-dict)
 
-(defcustom cider-completion-use-context t
-  "When true, uses context at point to improve completion suggestions."
-  :type 'boolean
-  :group 'cider
-  :package-version '(cider . "0.7.0"))
-
 (defcustom cider-annotate-completion-candidates t
   "When true, annotate completion candidates with some extra information."
   :type 'boolean
@@ -116,55 +112,6 @@ if the candidate is not namespace-qualified."
   :group 'cider
   :package-version '(cider . "0.9.0"))
 
-(defvar cider-completion-last-context nil)
-
-(defun cider-completion-symbol-start-pos ()
-  "Find the starting position of the symbol at point, unless inside a string."
-  (let ((sap (symbol-at-point)))
-    (when (and sap (not (nth 3 (syntax-ppss))))
-      (car (bounds-of-thing-at-point 'symbol)))))
-
-(defun cider-completion-get-context-at-point ()
-  "Extract the context at point.
-If point is not inside the list, returns nil; otherwise return \"top-level\"
-form, with symbol at point replaced by __prefix__."
-  (when (save-excursion
-          (condition-case _
-              (progn
-                (up-list)
-                (check-parens)
-                t)
-            (scan-error nil)
-            (user-error nil)))
-    (save-excursion
-      (let* ((pref-end (point))
-             (pref-start (cider-completion-symbol-start-pos))
-             (context (cider-defun-at-point))
-             (_ (beginning-of-defun-raw))
-             (expr-start (point)))
-        (concat (when pref-start (substring context 0 (- pref-start expr-start)))
-                "__prefix__"
-                (substring context (- pref-end expr-start)))))))
-
-(defun cider-completion-get-context ()
-  "Extract context depending on `cider-completion-use-context' and major mode."
-  (let ((context (if (and cider-completion-use-context
-                          ;; Important because `beginning-of-defun' and
-                          ;; `ending-of-defun' work incorrectly in the REPL
-                          ;; buffer, so context extraction fails there.
-                          (derived-mode-p 'clojure-mode))
-                     ;; We use ignore-errors here since grabbing the context
-                     ;; might fail because of unbalanced parens, or other
-                     ;; technical reasons, yet we don't want to lose all
-                     ;; completions and throw error to user because of that.
-                     (or (ignore-errors (cider-completion-get-context-at-point))
-                         "nil")
-                   "nil")))
-    (if (string= cider-completion-last-context context)
-        ":same"
-      (setq cider-completion-last-context context)
-      context)))
-
 (defun cider-completion--parse-candidate-map (candidate-map)
   "Get \"candidate\" from CANDIDATE-MAP.
 Put type and ns properties on the candidate"
@@ -253,7 +200,7 @@ performed by `cider-annotate-completion-function'."
                                                (cider-complete prefix) prefix pred)))))
             :annotation-function #'cider-annotate-symbol
             :company-kind #'cider-company-symbol-kind
-            :company-doc-buffer #'cider-create-doc-buffer
+            :company-doc-buffer #'cider-create-compact-doc-buffer
             :company-location #'cider-company-location
             :company-docsig #'cider-company-docsig))))
 
@@ -281,11 +228,10 @@ in the buffer."
 
 (defun cider-company-docsig (thing)
   "Return signature for THING."
-  (let* ((eldoc-info (cider-eldoc-info thing))
-         (ns (lax-plist-get eldoc-info "ns"))
-         (symbol (lax-plist-get eldoc-info "symbol"))
-         (arglists (lax-plist-get eldoc-info "arglists")))
-    (when eldoc-info
+  (when-let ((eldoc-info (cider-eldoc-info thing)))
+    (let* ((ns (lax-plist-get eldoc-info "ns"))
+           (symbol (lax-plist-get eldoc-info "symbol"))
+           (arglists (lax-plist-get eldoc-info "arglists")))
       (format "%s: %s"
               (cider-eldoc-format-thing ns symbol thing
                                         (cider-eldoc-thing-type eldoc-info))