Add cider-doc-map/menu and refactor cider-doc- into cider-doc-mode- prefix

5 files changed, 155 insertions, 102 deletions

diff --git a/cider-doc.el b/cider-doc.el
index 01803ad3..45cac0a0 100644
--- a/cider-doc.el
+++ b/cider-doc.el
@@ -1,4 +1,4 @@
-;;; cider-doc.el --- Documentation viewer -*- lexical-binding: t -*-
+;;; cider-doc.el --- CIDER documentation functionality -*- lexical-binding: t -*-
 
 ;; Copyright © 2014 Jeff Valk
 
@@ -31,97 +31,168 @@
 (require 'dash)
 (require 'easymenu)
 
-;; Variables
+
+;;; Variables
 
 (defgroup cider-doc nil
-  "Formatting/fontifying documentation viewer."
+  "Documentation for CIDER."
   :prefix "cider-doc-"
   :group 'cider)
 
-(defcustom cider-doc-fill-column fill-column
+
+(defvar cider-doc-map
+  (let (cider-doc-map)
+    (define-prefix-command 'cider-doc-map)
+    (define-key cider-doc-map (kbd "a") 'cider-apropos)
+    (define-key cider-doc-map (kbd "C-a") 'cider-apropos)
+    (define-key cider-doc-map (kbd "A") 'cider-apropos-documentation)
+    (define-key cider-doc-map (kbd "d") 'cider-doc)
+    (define-key cider-doc-map (kbd "C-d") 'cider-doc)
+    (define-key cider-doc-map (kbd "g") 'cider-grimoire)
+    (define-key cider-doc-map (kbd "C-g") 'cider-grimoire)
+    (define-key cider-doc-map (kbd "h") 'cider-grimoire-web)
+    (define-key cider-doc-map (kbd "j") 'cider-javadoc)
+    (define-key cider-doc-map (kbd "C-j") 'cider-javadoc)
+    cider-doc-map)
+  "CIDER documentation keymap.")
+
+(defvar cider-doc-menu
+  '("Documentation ..."
+    ["CiderDoc" cider-doc]
+    ["JavaDoc in browser" cider-javadoc]
+    ["Grimoire" cider-grimoire]
+    ["Grimoire in browser" cider-grimoire-web]
+    ["Search functions/vars" cider-apropos]
+    ["Search documentation" cider-apropos-documentation])
+  "CIDER documentation submenu.")
+
+
+
+;;; cider-docview-mode
+
+(defgroup cider-docview-mode nil
+  "Formatting/fontifying documentation viewer."
+  :prefix "cider-docview-"
+  :group 'cider)
+
+(defcustom cider-docview-fill-column fill-column
   "Fill column for docstrings in doc buffer."
   :type 'list
-  :group 'cider-doc
+  :group 'cider-docview-mode
   :package-version '(cider . "0.7.0"))
 
 
+
 ;; Faces
 
-(defface cider-doc-emphasis-face
+(defface cider-docview-emphasis-face
   '((t (:inherit default :underline t)))
   "Face for emphasized text"
-  :group 'cider-doc
+  :group 'cider-docview-mode
   :package-version '(cider . "0.7.0"))
 
-(defface cider-doc-strong-face
+(defface cider-docview-strong-face
   '((t (:inherit default :underline t :weight bold)))
   "Face for strongly emphasized text"
-  :group 'cider-doc
+  :group 'cider-docview-mode
   :package-version '(cider . "0.7.0"))
 
-(defface cider-doc-literal-face
+(defface cider-docview-literal-face
   '((t (:inherit font-lock-string-face)))
   "Face for literal text"
-  :group 'cider-doc
+  :group 'cider-docview-mode
   :package-version '(cider . "0.7.0"))
 
-(defface cider-doc-table-border-face
+(defface cider-docview-table-border-face
   '((t (:inherit shadow)))
   "Face for table borders"
-  :group 'cider-doc
+  :group 'cider-docview-mode
   :package-version '(cider . "0.7.0"))
 
-
+
 ;; Colors & Theme Support
 
-(defvar cider-doc-code-background-color
+(defvar cider-docview-code-background-color
   (cider-scale-background-color)
   "Background color for code blocks.")
 
-(defadvice enable-theme (after cider-doc-adapt-to-theme activate)
-  "When theme is changed, update `cider-doc-code-background-color'."
-  (setq cider-doc-code-background-color (cider-scale-background-color)))
-
+(defadvice enable-theme (after cider-docview-adapt-to-theme activate)
+  "When theme is changed, update `cider-docview-code-background-color'."
+  (setq cider-docview-code-background-color (cider-scale-background-color)))
 
+
 ;; Mode & key bindings
 
-(defvar cider-doc-mode-map
+(defvar cider-docview-mode-map
   (let ((map (make-sparse-keymap)))
     (define-key map "q" 'cider-popup-buffer-quit-function)
-    (define-key map "j" 'cider-doc-javadoc)
+    (define-key map "j" 'cider-docview-javadoc)
     (define-key map (kbd "<backtab>") 'backward-button)
     (define-key map (kbd "TAB") 'forward-button)
-    (easy-menu-define cider-doc-mode-menu map
+
+    ;; VS[04-08-2014]: proposed keybindings for the docview mode
+    ;; (define-key map (kbd "<backtab>") 'backward-button)
+    ;; (define-key map (kbd "TAB") 'forward-button)
+    ;; (define-key map (kbd "k") 'kill-this-buffer)
+    
+    ;; (define-key map (kbd "C-c C-d") 'cider-doc-map)
+    ;; (define-key map (kbd "a") 'cider-apropos)
+    ;; (define-key map (kbd "A") 'cider-apropos-documentation)
+    ;; (define-key map (kbd "d") 'cider-doc)
+    ;; (define-key map (kbd "g") 'cider-grimoire)
+    ;; (define-key map (kbd "h") 'cider-grimoire-web)
+    ;; (define-key map (kbd "j") 'cider-javadoc)
+    ;; (define-key map (kbd "J") 'cider-doc-javadoc)
+
+    ;; (define-key map (kbd "M-.") 'cider-jump-to-var)
+    ;; (define-key map (kbd "M-,") 'cider-jump-back)
+    ;; (define-key map (kbd "C-c M-.") 'cider-jump-to-resource)
+    ;; (define-key map (kbd "i") 'cider-inspect)
+    ;; (define-key map (kbd "C-c M-i") 'cider-inspect)
+    ;; (define-key map (kbd "C-c C-z") 'cider-switch-to-repl-buffer)
+
+    (easy-menu-define cider-docview-mode-menu map
       "Menu for CIDER's doc mode"
-      '("Doc"
-        ["Go to Javadoc" cider-doc-javadoc]
-        ["Quit" cider-popup-buffer-quit-function]))
+      `("Doc"
+        ;; ,cider-doc-menu
+        ;; "--"
+        ;; ["Jump to source" cider-jump-to-var]
+        ;; ["Jump to resource" cider-jump-to-resource]
+        ;; ["Jump back" cider-jump-back]
+        ;; "--"
+        ;; ["Switch to REPL" cider-switch-to-repl-buffer]
+        ;; "--"
+        ;; ["Kill" kill-this-buffer]
+        ;; ["Quit" quit-window]
+        ["JavaDoc in browser" cider-docview-javadoc]
+        ["Quit" cider-popup-buffer-quit-function]
+        ))
     map))
 
-(define-derived-mode cider-doc-mode fundamental-mode "Doc"
+(define-derived-mode cider-docview-mode special-mode "Doc"
   "Major mode for displaying CIDER documentation
 
-\\{cider-doc-mode-map}"
+\\{cider-docview-mode-map}"
   (setq buffer-read-only t)
   (setq-local truncate-lines t)
   (setq-local electric-indent-chars nil)
-  (setq-local cider-doc-symbol nil)
-  (setq-local cider-doc-javadoc-url nil))
-
+  (setq-local cider-docview-symbol nil)
+  (setq-local cider-docview-javadoc-url nil))
 
-;; Interactive functions
+
+;;; Interactive functions
 
-(defun cider-doc-javadoc ()
+(defun cider-docview-javadoc ()
   "Open the Javadoc for the current class, if available."
   (interactive)
-  (if cider-doc-javadoc-url
-      (browse-url cider-doc-javadoc-url)
-    (message "No Javadoc available for %s" cider-doc-symbol)))
+  (if cider-docview-javadoc-url
+      (browse-url cider-docview-javadoc-url)
+    (message "No Javadoc available for %s" cider-docview-symbol)))
 
+
+;;; Font Lock and Formatting
 
-;; Font Lock and Formatting
-
-(defun cider-doc-fontify-code-blocks (buffer mode)
+(defun cider-docview-fontify-code-blocks (buffer mode)
   "Font lock BUFFER code blocks using MODE and remove markdown characters.
 This processes the triple backtick GFM markdown extension.  An overlay is used
 to shade the background.  Blocks are marked to be ignored by other fonification
@@ -131,14 +202,14 @@ and line wrap."
       (while (search-forward-regexp "```\n" nil t)
         (replace-match "")
         (let ((beg (point))
-              (bg `(:background ,cider-doc-code-background-color)))
+              (bg `(:background ,cider-docview-code-background-color)))
           (when (search-forward-regexp "```\n" nil t)
             (replace-match "")
             (cider-font-lock-region-as mode beg (point))
             (overlay-put (make-overlay beg (point)) 'face bg)
             (put-text-property beg (point) 'block 'code)))))))
 
-(defun cider-doc-fontify-literals (buffer)
+(defun cider-docview-fontify-literals (buffer)
   "Font lock BUFFER literal text and remove backtick markdown characters.
 Preformatted code text blocks are ignored."
   (with-current-buffer buffer
@@ -151,9 +222,9 @@ Preformatted code text blocks are ignored."
             (let ((beg (point)))
               (when (search-forward "`" (line-end-position) t)
                 (replace-match "")
-                (put-text-property beg (point) 'face 'cider-doc-literal-face)))))))))
+                (put-text-property beg (point) 'face 'cider-docview-literal-face)))))))))
 
-(defun cider-doc-fontify-emphasis (buffer)
+(defun cider-docview-fontify-emphasis (buffer)
   "Font lock BUFFER emphasized text and remove markdown characters.
 One '*' represents emphasis, multiple '**'s represent strong emphasis.
 Preformatted code text blocks are ignored."
@@ -166,19 +237,19 @@ Preformatted code text blocks are ignored."
             (replace-match "\\2")
             (let ((beg (1- (point)))
                   (face (if (> (length (match-string 1)) 1)
-                            'cider-doc-strong-face
-                          'cider-doc-emphasis-face)))
+                            'cider-docview-strong-face
+                          'cider-docview-emphasis-face)))
               (when (search-forward-regexp "\\(\\w\\)\\*+" (line-end-position) t)
                 (replace-match "\\1")
                 (put-text-property beg (point) 'face face)))))))))
 
-(defun cider-doc-format-tables (buffer)
+(defun cider-docview-format-tables (buffer)
   "Align BUFFER tables and dim borders.
 This processes the GFM table markdown extension using `org-table'.
 Tables are marked to be ignored by line wrap."
   (with-current-buffer buffer
     (save-excursion
-      (let ((border 'cider-doc-table-border-face))
+      (let ((border 'cider-docview-table-border-face))
         (org-table-map-tables
          (lambda ()
            (org-table-align)
@@ -187,7 +258,7 @@ Tables are marked to be ignored by line wrap."
              (put-text-property (match-beginning 0) (match-end 0) 'face border))
            (put-text-property (org-table-begin) (org-table-end) 'block 'table)))))))
 
-(defun cider-doc-wrap-text (buffer)
+(defun cider-docview-wrap-text (buffer)
   "For text in BUFFER not propertized as 'block', apply line wrap."
   (with-current-buffer buffer
     (save-excursion
@@ -196,23 +267,23 @@ Tables are marked to be ignored by line wrap."
           (fill-region (point) (line-end-position)))
         (forward-line)))))
 
+
+;;; Rendering
 
-;; Rendering
-
-(defun cider-doc-render-java-doc (buffer text)
+(defun cider-docview-render-java-doc (buffer text)
   "Emit into BUFFER formatted doc TEXT for a Java class or member."
   (with-current-buffer buffer
     (let ((beg (point)))
       (insert text)
       (save-excursion
         (goto-char beg)
-        (cider-doc-fontify-code-blocks buffer 'java-mode) ; left alone hereafter
-        (cider-doc-fontify-literals buffer)
-        (cider-doc-fontify-emphasis buffer)
-        (cider-doc-format-tables buffer) ; may contain literals, emphasis
-        (cider-doc-wrap-text buffer))))) ; ignores code, table blocks
+        (cider-docview-fontify-code-blocks buffer 'java-mode) ; left alone hereafter
+        (cider-docview-fontify-literals buffer)
+        (cider-docview-fontify-emphasis buffer)
+        (cider-docview-format-tables buffer) ; may contain literals, emphasis
+        (cider-docview-wrap-text buffer))))) ; ignores code, table blocks
 
-(defun cider-doc-render-info (buffer info)
+(defun cider-docview-render-info (buffer info)
   "Emit into BUFFER formatted INFO for the Clojure or Java symbol."
   (let* ((ns      (cadr (assoc "ns" info)))
          (name    (cadr (assoc "name" info)))
@@ -256,7 +327,7 @@ Tables are marked to be ignored by line wrap."
           (emit (concat "Deprecated in " depr) 'font-lock-comment-face))
         (when doc
           (if class
-              (cider-doc-render-java-doc (current-buffer) doc)
+              (cider-docview-render-java-doc (current-buffer) doc)
             (emit (concat "  " doc))))
         (when url
           (newline)
@@ -284,22 +355,23 @@ Tables are marked to be ignored by line wrap."
             (put-text-property beg end (car x) (cadr x)))))
       (current-buffer))))
 
-(defun cider-doc-render (buffer symbol info)
+(defun cider-docview-render (buffer symbol info)
   "Emit into BUFFER formatted documentation for SYMBOL's INFO."
   (with-current-buffer buffer
     (let ((javadoc (cadr (assoc "javadoc" info)))
           (inhibit-read-only t))
-      (cider-doc-mode)
+      (cider-docview-mode)
 
-      (setq-local cider-doc-symbol symbol)
-      (setq-local cider-doc-javadoc-url javadoc)
+      (setq-local cider-docview-symbol symbol)
+      (setq-local cider-docview-javadoc-url javadoc)
 
       (remove-overlays)
-      (cider-doc-render-info buffer info)
+      (cider-docview-render-info buffer info)
 
       (goto-char (point-min))
       (current-buffer))))
 
+
 (provide 'cider-doc)
 
 ;;; cider-doc.el ends here
diff --git a/cider-interaction.el b/cider-interaction.el
index 8920d5f1..ee0cdeeb 100644
--- a/cider-interaction.el
+++ b/cider-interaction.el
@@ -1396,7 +1396,7 @@ point, prompts for a var."
 (defun cider-create-doc-buffer (symbol)
   "Populates *cider-doc* with the documentation for SYMBOL."
   (-when-let (info (cider-var-info symbol))
-    (cider-doc-render (cider-make-popup-buffer cider-doc-buffer) symbol info)))
+    (cider-docview-render (cider-make-popup-buffer cider-doc-buffer) symbol info)))
 
 (defun cider-doc-lookup (symbol)
   "Look up documentation for SYMBOL."
diff --git a/cider-macroexpansion.el b/cider-macroexpansion.el
index c672aea6..61042f8d 100644
--- a/cider-macroexpansion.el
+++ b/cider-macroexpansion.el
@@ -167,7 +167,7 @@ and point is placed after the expanded form."
         ["Macroexpand-all" cider-macroexpand-all-inplace]
         ["Go to source" cider-jump-to-var]
         ["Go to doc" cider-doc]
-        ["Go to Javadoc" cider-doc-javadoc]
+        ["Go to Javadoc" cider-docview-javadoc]
         ["Quit" cider-popup-buffer-quit-function]))
     (cl-labels ((redefine-key (from to)
                               (dolist (mapping (where-is-internal from cider-mode-map))
diff --git a/cider-mode.el b/cider-mode.el
index 75d9fa39..d92bff41 100644
--- a/cider-mode.el
+++ b/cider-mode.el
@@ -52,16 +52,11 @@ entirely."
 
 (defvar cider-mode-map
   (let ((map (make-sparse-keymap)))
-    (define-key map (kbd "M-.") 'cider-jump)
+    (define-key map (kbd "C-c C-d") 'cider-doc-map)
+    (define-key map (kbd "M-.") 'cider-jump-to-var)
     (define-key map (kbd "M-,") 'cider-jump-back)
     (define-key map (kbd "C-c M-.") 'cider-jump-to-resource)
     (define-key map (kbd "M-TAB") 'complete-symbol)
-    (define-key map (kbd "C-c C-d a") 'cider-apropos)
-    (define-key map (kbd "C-c C-d A") 'cider-apropos-documentation)
-    (define-key map (kbd "C-c C-d g") 'cider-grimoire)
-    (define-key map (kbd "C-c C-d h") 'cider-grimoire-web)
-    (define-key map (kbd "C-c C-d j") 'cider-javadoc)
-    (define-key map (kbd "C-c C-d d") 'cider-doc)
     (define-key map (kbd "C-M-x")   'cider-eval-defun-at-point)
     (define-key map (kbd "C-c C-c") 'cider-eval-defun-at-point)
     (define-key map (kbd "C-x C-e") 'cider-eval-last-sexp)
@@ -95,14 +90,16 @@ entirely."
     (define-key map (kbd "C-c C-q") 'cider-quit)
     (easy-menu-define cider-mode-menu map
       "Menu for CIDER mode"
-      '("CIDER"
+      `("CIDER"
         ["Complete symbol" complete-symbol]
         "--"
+        ,cider-doc-menu
+        "--"
         ["Eval top-level sexp at point" cider-eval-defun-at-point]
         ["Eval last sexp" cider-eval-last-sexp]
         ["Eval last sexp in popup buffer" cider-pprint-eval-last-sexp]
         ["Eval last sexp to REPL buffer" cider-eval-last-sexp-to-repl]
-        ["Eval last sexp and replace it with its result" cider-eval-last-sexp-and-replace]
+        ["Eval last sexp and replace" cider-eval-last-sexp-and-replace]
         ["Eval region" cider-eval-region]
         ["Eval ns form" cider-eval-ns-form]
         ["Insert last sexp in REPL" cider-insert-last-sexp-in-repl]
@@ -110,27 +107,20 @@ entirely."
         ["Load current buffer" cider-load-current-buffer]
         ["Load file" cider-load-file]
         "--"
-        ["Macroexpand-1 last expression" cider-macroexpand-1]
-        ["Macroexpand-all last expression" cider-macroexpand-all]
+        ["Macroexpand-1" cider-macroexpand-1]
+        ["Macroexpand-all" cider-macroexpand-all]
         "--"
-        ["Jump to source" cider-jump]
+        ["Jump to source" cider-jump-to-var]
         ["Jump to resource" cider-jump-to-resource]
         ["Jump back" cider-jump-back]
         "--"
-        ["Search functions/vars" cider-apropos]
-        ["Search documentation" cider-apropos-documentation]
-        "--"
-        ["Display documentation" cider-doc]
-        ["Display JavaDoc" cider-javadoc]
-        ["Display Grimoire documentation" cider-grimoire]
-        ["Display Grimoire documentation in browser" cider-grimoire-web]
-        ["Inspect" cider-inspect]
-        "--"
         ["Run test" cider-test-run-test]
         ["Run all tests" cider-test-run-tests]
         ["Rerun failed/erring tests" cider-test-rerun-tests]
         ["Show test report" cider-test-show-report]
         "--"
+        ["Inspect" cider-inspect]
+        "--"
         ["Set ns" cider-repl-set-ns]
         ["Switch to REPL" cider-switch-to-repl-buffer]
         ["Switch to Relevant REPL" cider-switch-to-relevant-repl-buffer]
@@ -141,8 +131,8 @@ entirely."
         ["Quit" cider-quit]
         ["Restart" cider-restart]
         "--"
-        ["Display current nREPL connection" cider-display-current-connection-info]
-        ["Rotate current nREPL connection" cider-rotate-connection]
+        ["Display nREPL connection" cider-display-current-connection-info]
+        ["Rotate nREPL connection" cider-rotate-connection]
         "--"
         ["Version info" cider-version]))
     map))
diff --git a/cider-repl.el b/cider-repl.el
index abbe9796..9b0b965c 100644
--- a/cider-repl.el
+++ b/cider-repl.el
@@ -32,6 +32,7 @@
 
 (require 'cider-client)
 (require 'cider-interaction)
+(require 'cider-doc)
 (require 'cider-eldoc) ; for cider-turn-on-eldoc-mode
 (require 'cider-util)
 
@@ -981,6 +982,7 @@ ENDP) DELIM."
 (defvar cider-repl-mode-map
   (let ((map (make-sparse-keymap)))
     (set-keymap-parent map clojure-mode-map)
+    (define-key map (kbd "C-c C-d") 'cider-doc-map)
     (define-key map (kbd "M-.") 'cider-jump)
     (define-key map (kbd "M-,") 'cider-jump-back)
     (define-key map (kbd "C-c M-.") 'cider-jump-to-resource)
@@ -988,12 +990,6 @@ ENDP) DELIM."
     (define-key map (kbd "TAB") 'cider-repl-tab)
     (define-key map (kbd "C-<return>") 'cider-repl-closing-return)
     (define-key map (kbd "C-j") 'cider-repl-newline-and-indent)
-    (define-key map (kbd "C-c C-d a") 'cider-apropos)
-    (define-key map (kbd "C-c C-d A") 'cider-apropos-documentation)
-    (define-key map (kbd "C-c C-d g") 'cider-grimoire)
-    (define-key map (kbd "C-c C-d h") 'cider-grimoire-web)
-    (define-key map (kbd "C-c C-d d") 'cider-doc)
-    (define-key map (kbd "C-c C-d j") 'cider-javadoc)
     (define-key map (kbd "C-c C-o") 'cider-repl-clear-output)
     (define-key map (kbd "C-c M-o") 'cider-repl-clear-buffer)
     (define-key map (kbd "C-c M-n") 'cider-repl-set-ns)
@@ -1026,24 +1022,19 @@ ENDP) DELIM."
     (define-key map (string cider-repl-shortcut-dispatch-char) 'cider-repl-handle-shortcut)
     (easy-menu-define cider-repl-mode-menu map
       "Menu for CIDER's REPL mode"
-      '("REPL"
+      `("REPL"
         ["Complete symbol" complete-symbol]
         "--"
+        ,cider-doc-menu
+        "--"
         ["Jump to source" cider-jump]
         ["Jump to resource" cider-jump-to-resource]
         ["Jump back" cider-jump-back]
         "--"
-        ["Search functions/vars" cider-apropos]
-        ["Search documentation" cider-apropos-documentation]
-        "--"
-        ["Display documentation" cider-doc]
-        ["Display JavaDoc" cider-javadoc]
-        ["Display Grimoire documentation" cider-grimoire]
-        ["Display Grimoire documentation in browser" cider-grimoire-web]
         ["Inspect" cider-inspect]
         "--"
         ["Set REPL ns" cider-repl-set-ns]
-        ["Toggle pretty printing of results" cider-repl-toggle-pretty-printing]
+        ["Toggle pretty printing" cider-repl-toggle-pretty-printing]
         ["Clear output" cider-repl-clear-output]
         ["Clear buffer" cider-repl-clear-buffer]
         ["Refresh loaded code" cider-refresh]