/
cider-docstring.el
165 lines (142 loc) · 7.61 KB
/
cider-docstring.el
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
;;; cider-docstring.el --- Docstring rendering -*- lexical-binding: t -*-
;; Copyright © 2013-2024 Bozhidar Batsov and CIDER contributors
;;
;; Author: Bozhidar Batsov <bozhidar@batsov.dev>
;; 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:
;; Utilities for rendering a docstring into a shorter, especially-formatted string
;; that will look nice in UIs.
;;; Code:
(require 'cl-lib)
(require 'shr)
(defsubst cider--render-pre* (dom)
"Render DOM nodes, formatting them them as Java if they are strings."
(dolist (sub (dom-children dom))
(if (stringp sub)
(shr-insert (cider-font-lock-as 'java-mode sub))
(shr-descend sub))))
(defun cider--render-pre (dom)
"Render DOM nodes without folding, a monospaced font, and Java syntax coloring."
(let ((shr-folding-mode 'none)
(shr-current-font 'default))
(cider--render-pre* dom)))
(defun cider--string-rstrip-newlines (str)
"Remove newlines at the end of STR."
(if (string-match "\\([\n\r]+\\)$" str)
(replace-match "" nil nil str)
str))
(defun cider--html-to-propertized-string (html-string)
"Convert an HTML-STRING into a propertized string using SHR."
(with-temp-buffer
(insert html-string)
(cider--string-rstrip-newlines ;; shr-insert-document adds a final newline. Plain text fragments are responsible for separating fragments if needed..
(let ((dom (libxml-parse-html-region (point-min) (point-max))))
(erase-buffer)
(shr-insert-document dom)
(buffer-string)))))
(defun cider--fragments-to-s (fragments)
"Convert FRAGMENTS into a concatenated string representation.
If a given fragment is of html type, it's converted to a propertized string;
otherwise, it's included as-is."
(when (and fragments
(> (length fragments)
0))
(string-trim (cl-reduce (lambda (new-s fragment)
(let* ((html? (equal "html" (nrepl-dict-get fragment "type")))
(v (nrepl-dict-get fragment "content")))
(concat new-s (if html?
(let ((shr-use-fonts nil)
(shr-external-rendering-functions '((pre . cider--render-pre))))
(cider--html-to-propertized-string v))
v))))
fragments
:initial-value ""))))
(defcustom cider-docstring-max-lines 20
"The maximum number of docstring lines that will be rendered in a UI widget (or the echo area).
Note that `cider-docstring' will trim thing smartly, for Java doc comments:
* First, the whole doc comment will be attempted to be rendered.
* If that exceeds `cider-docstring-max-lines',
we will use only the first sentence and the block tags
(that is, the params/throws/returns info).
* If that exceeds `cider-docstring-max-lines', we will use only the block tags.
* If that exceeds `cider-docstring-max-lines', we will use only the first sentence."
:type 'integer
:group 'cider
:package-version '(cider . "1.8.0"))
(defun cider--attempt-invalid? (attempt)
"Check if ATTEMPT is either nil or exceeds `cider-docstring-max-lines' in line count."
(or (not attempt)
(and attempt
(> (length (split-string attempt "\n"))
cider-docstring-max-lines))))
(defun cider--render-docstring-first-sentence (eldoc-info)
"Render the first sentence of the docstring extracted from ELDOC-INFO."
(when-let ((first-sentence-fragments (lax-plist-get eldoc-info "doc-first-sentence-fragments")))
(cider--fragments-to-s first-sentence-fragments)))
(defun cider--render-docstring (eldoc-info)
"Renders the docstring from ELDOC-INFO based on its length and content.
Prioritize rendering as much as possible while staying within `cider-docstring-max-lines'."
(let* ((first-sentence-fragments (lax-plist-get eldoc-info "doc-first-sentence-fragments"))
(body-fragments (lax-plist-get eldoc-info "doc-fragments"))
(block-tags-fragments (lax-plist-get eldoc-info "doc-block-tags-fragments"))
(block-tags-fragments-rendered (cider--fragments-to-s block-tags-fragments))
(first-sentence-fragments-rendered) ;; mutable, for performance
(first-attempt (when body-fragments
(concat (cider--fragments-to-s body-fragments)
(when block-tags-fragments
"\n\n")
block-tags-fragments-rendered)))
(first-attempt-invalid? (cider--attempt-invalid? first-attempt))
(second-attempt (when (and first-sentence-fragments
first-attempt-invalid?)
(setq first-sentence-fragments-rendered (cider--fragments-to-s first-sentence-fragments))
(concat first-sentence-fragments-rendered
(when block-tags-fragments-rendered
"\n\n")
block-tags-fragments-rendered)))
(second-attempt-invalid? (cider--attempt-invalid? second-attempt))
(third-attempt (when (and block-tags-fragments-rendered
first-attempt-invalid?
second-attempt-invalid?)
block-tags-fragments-rendered))
(third-attempt-invalid? (cider--attempt-invalid? third-attempt))
(last-attempt (when (and first-sentence-fragments-rendered
first-attempt-invalid?
second-attempt-invalid?
third-attempt-invalid?)
first-sentence-fragments-rendered)))
(or last-attempt ;; the last attempt has to go first - it takes priority over an attempt deemed invalid.
third-attempt
second-attempt
first-attempt)))
(defun cider-docstring--dumb-trim (s &optional n)
"Returns up to the first N lines of string S,
adding \"...\" if trimming was necessary.
N defaults to `cider-docstring-max-lines'.
Also performs some bare-bones formatting, cleaning up some common whitespace issues."
(when s
(let* ((s (replace-regexp-in-string "\\. " ".\n\n" s)) ;; improve the formatting of e.g. clojure.core/reduce
(n (or n cider-docstring-max-lines))
(lines (split-string s "\n"))
(lines-length (length lines))
(selected-lines (cl-subseq lines 0 (min n lines-length)))
(result (mapconcat (lambda (f)
;; Remove spaces at the beginning of each line, as it is common in many clojure.core defns:
(replace-regexp-in-string "\\`[ ]+" "" f))
selected-lines
"\n")))
(if (> lines-length n)
(concat result "...")
result))))
(provide 'cider-docstring)
;;; cider-docstring.el ends here