diff options
| -rw-r--r-- | CHANGELOG.md | 1 | ||||
| -rw-r--r-- | cider-doc.el | 3 | ||||
| -rw-r--r-- | cider-util.el | 66 | ||||
| -rw-r--r-- | doc/images/cider_see_also.gif | bin | 0 -> 671096 bytes | |||
| -rw-r--r-- | doc/miscellaneous_features.md | 29 |
5 files changed, 97 insertions, 2 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index e3832c34..ed49fe75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ * [#1564](https://github.com/clojure-emacs/cider/issues/1564): CIDER's internal namespaces and vars are filtered from the ns-browser and apropos functions. * [#1725](https://github.com/clojure-emacs/cider/issues/1725): Display class names in eldoc for interop forms. * [#1572](https://github.com/clojure-emacs/cider/issues/1572): Add support for variables in eldoc. +* [#1736](https://github.com/clojure-emacs/cider/issues/1736): Show "See Also" links for functions/variables in documentation buffers. ### Changes diff --git a/cider-doc.el b/cider-doc.el index 8d4f7418..fe64aaf3 100644 --- a/cider-doc.el +++ b/cider-doc.el @@ -456,7 +456,6 @@ Tables are marked to be ignored by line wrap." (when see-also (insert "\n\n Also see: ") (mapc (lambda (ns-sym) - (let* ((ns-sym-split (split-string ns-sym "/")) (see-also-ns (car ns-sym-split)) (see-also-sym (cadr ns-sym-split)) @@ -468,7 +467,7 @@ Tables are marked to be ignored by line wrap." 'help-function (apply-partially #'cider-doc-lookup symbol))) (insert " ")) see-also)) - (help-make-xrefs) + (cider--help-make-xrefs) (let ((beg (point-min)) (end (point-max))) (nrepl-dict-map (lambda (k v) diff --git a/cider-util.el b/cider-util.el index 920c32f3..0a0725f9 100644 --- a/cider-util.el +++ b/cider-util.el @@ -454,6 +454,72 @@ restore it properly when going back." (if tail (setcdr tail nil)))) (setq help-xref-stack-item item))) +(defcustom cider-doc-xref-regexp "`\\(.*?\\)`" + "The regexp used to search Clojure vars in doc buffers." + :type 'regexp + :safe #'stringp + :group 'cider + :package-version '(cider . "0.13.0")) + +(defun cider--parse-symbol-docstring (&optional buffer) + "Parse and return the first clojure symbol in BUFFER. +Uses `cider-doc-xref-regexp' to search the symbols. +Return nil if there are no more matches in the buffer." + (with-current-buffer (or buffer (current-buffer)) + (when (re-search-forward cider-doc-xref-regexp nil t) + (list "symbol" (match-string 1) + "beg" (match-beginning 1) + "end" (match-end 1))))) + +(declare-function cider-doc-lookup "cider-doc") +(declare-function cider--eldoc-remove-dot "cider-eldoc") + +;; Similar to https://github.com/emacs-mirror/emacs/blob/65c8c7cb96c14f9c6accd03cc8851b5a3459049e/lisp/help-mode.el#L404 +(defun cider--help-make-xrefs (&optional buffer) + "Parse and hyperlink documentation cross-references in the given BUFFER. + +Find cross-reference information in a buffer and activate such cross +references for selection with `help-xref'. Cross-references are parsed +using `cider--parse-symbol-docstring.'. + +A special reference `back' is made to return back through a stack of +help buffers. Variable `help-back-label' specifies the text for +that. A similar reference `forward' is made to traverse in the opposite +direction. Variable `help-forward-label' specifies the text for that." + (interactive "b") + + ;; parse the docstring and create xrefs for symbols + (save-excursion + (goto-char (point-min)) + (if-let ((current-sym (cider--parse-symbol-docstring))) + (while current-sym + (when-let ((symbol (lax-plist-get current-sym "symbol")) + (beg (lax-plist-get current-sym "beg")) + (end (lax-plist-get current-sym "end"))) + (make-text-button beg end + 'type 'help-xref + 'help-function (apply-partially #'cider-doc-lookup + (cider--eldoc-remove-dot symbol)))) + (setq current-sym (cider--parse-symbol-docstring))))) + + ;; create back and forward buttons if appropiate + (with-current-buffer (or buffer (current-buffer)) + (insert "\n") + (when (or help-xref-stack help-xref-forward-stack) + (insert "\n")) + ;; Make a back-reference in this buffer if appropriate. + (when help-xref-stack + (help-insert-xref-button help-back-label 'help-back + (current-buffer))) + ;; Make a forward-reference in this buffer if appropriate. + (when help-xref-forward-stack + (when help-xref-stack + (insert "\t")) + (help-insert-xref-button help-forward-label 'help-forward + (current-buffer))) + (when (or help-xref-stack help-xref-forward-stack) + (insert "\n")))) + ;;; Words of inspiration (defun cider-user-first-name () diff --git a/doc/images/cider_see_also.gif b/doc/images/cider_see_also.gif Binary files differnew file mode 100644 index 00000000..7931aeac --- /dev/null +++ b/doc/images/cider_see_also.gif diff --git a/doc/miscellaneous_features.md b/doc/miscellaneous_features.md index 8a0d5052..8dc78065 100644 --- a/doc/miscellaneous_features.md +++ b/doc/miscellaneous_features.md @@ -185,3 +185,32 @@ Keyboard shortcut | Description <kbd>^</kbd> | Browse all namespaces. <kbd>n</kbd> | Go to next line. <kbd>p</kbd> | Go to previous line. + +## Documentation buffers include "See Also" references + +You can add references to other vars by including their names in `` ` `` in the docstring. +If the var is in another namespace, then you'll have to include the full +namespace qualified name in the docstring. If you want to use some other delimiter instead +of the backticks, you'll have to update the value of `cider-doc-xref-regexp` to match that. +The first group of the regexp should always match the var name. + +As an example, if you want to want to use the delimiter style used by +[Codox](https://github.com/weavejester/codox) (`[[...]]`) the regexp would be; + +``` +(setq cider-doc-xref-regexp "\\[\\[\\(.*?\\)\\]\\]") +``` + + + +Example function with a docstring containing references: + +``` +(defn test-fn + "Test function. + Also see: `clojure.core/map`, `clojure.core/reduce`, `defn`. + You can reference variables like `thor`, `kubaru.data.zookeeper/yoda`. + Also works with references to java interop forms, `java.lang.String/.length`." + [] + (+ 1 1)) +``` |
