branch: elpa/eldoc-mouse
commit dcb1718e5d6e499391baba3645aaf0d1ab9d8b35
Author: huangfeiyu <[email protected]>
Commit: GitHub <[email protected]>
Revise README for eldoc-mouse clarity and details
Updated README to clarify eldoc-mouse features and installation
instructions.
---
README.md | 50 +++++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 43 insertions(+), 7 deletions(-)
diff --git a/README.md b/README.md
index a7c38611137..256e4ddf897 100644
--- a/README.md
+++ b/README.md
@@ -2,20 +2,20 @@
# eldoc-mouse
-`eldoc-mouse` is an Emacs package that enhances the `eldoc` functionality by
displaying documentation in a popup at the mouse point using
[posframe](https://github.com/tumashu/posframe) when the mouse hovers over a
symbol in an `eglot` managed buffer. It integrates with `posframe` to provide
popping up documentation and features a debounced hover mechanism to prevent
excessive requests to the LSP server.
+`eldoc-mouse` is an Emacs package that enhances the `eldoc` functionality by
displaying documentation in a popup at the mouse point using
[posframe](https://github.com/tumashu/posframe) when the mouse hovers over a
symbol. It integrates with `posframe` to provide popping up documentation.
[Eldoc-mouse Demo at Youtube](https://youtu.be/XFAc4WyiJjI)
<video
src="https://github.com/user-attachments/assets/5622cfd2-de0c-46e8-9276-d67615671932";
controls></video>
## Features
-- Displays documentation in a popup when hovering over symbols in `eglot`
managed buffers.
+- Displays documentation in a popup when hovering over symbols.
- Integrates with `posframe` for popup documentation.
- Support moving mouse to the popup by move mouse on it and click.
- Automatically hide the popup when mouse moved away from the symbol, also
supoort pressing `C-g` to hide the popup.
-- Avoids spamming the LSP server by debouncing hover events.
-- Works in eglot managed buffers to show documentation for the symbol under
the mouse point.
-- Removed the unnecessary signatures from the document to make doucment more
clear.
-- Still keep highlighting the symbol under the cursor.
+- The following enhancements are made for eglot managed buffers.
+ - Removed the unnecessary signatures from the document to make doucment
more clear.
+ - Still keep highlighting the symbol under the cursor.
- An interactive command to pop up document at cursor
`eldoc-mouse-pop-doc-at-cursor`, this is helpful when you don't bother to move
mouse, but want to check document. I bind it to key sequence `F1 F1`, press
Ctrl-G or moving cursor away from the current symbol to close the popup.
+- More modes can be easily supported by extends `eldoc-mouse`.
- So far, `eldoc-mouse` works only for GUI Emacs.
## Installation
@@ -31,12 +31,48 @@ You can install `eldoc-mouse` with the following command.
Add the following in your Emacs configuration:
```
;; The following two lines are both optional, but you would like to add at
least one of them to your Emacs configuration.
-(use-package eldoc-mouse :hook (eglot-managed-mode)) ;; enable mouse hover for
eglot managed buffers.
+(use-package eldoc-mouse :hook (eglot-managed-mode emacs-lisp-mode)) ;; enable
mouse hover for eglot managed buffers, and emacs lisp buffers.
(global-set-key (kbd "<f1> <f1>") 'eldoc-mouse-pop-doc-at-cursor) ;; replace
<f1> <f1> to a key you like. Displaying document on a popup when you press a
key.
```
+### Supported modes
+* eglot-managed-mode
+* emacs-list-mode
## Customization
You can customize the behavior of eldoc-mouse by adjusting the variables. For
instance, you can adjust the delay time between mouse hover and displaying the
documentation by changing the eldoc-mouse-mouse-timer settings.
+
+## Extend (Add new mode)
+`eldoc-mouse` can be easily extended to support more major/minor modes, finish
the following 3 steps to extend it to support a new mode.
+
+1. write an impementation of `eldoc-documentation-functions`. see
https://www.gnu.org/software/emacs/manual/html_node/emacs/Programming-Language-Doc.html#index-eldoc_002ddocumentation_002dfunctions.
Here's an example implementation for `emacs-lisp-mode`
+ ```elisp
+ (defun eldoc-mouse--elisp-eldoc-documentation-function (_cb)
+ "The `eldoc-documentation-functions' implementation for elisp."
+ (if (eq major-mode 'emacs-lisp-mode)
+ (let ((sym (symbol-at-point)))
+ (cond
+ ;; If the symbol is a function
+ ((and sym (fboundp sym))
+ (documentation sym))
+ ;; If the symbol is a variable
+ ((and sym (boundp sym))
+ (let ((doc (documentation-property sym 'variable-documentation)))
+ (if doc
+ doc
+ nil)))
+ ;; If no symbol or not a function/variable
+ (t nil)))
+ nil)) ;; if the expected mode is not available, nil should be returned.
+ ```
+2. add the function name to the `eldoc-mouse` variable
`eldoc-mouse--eldoc-documentation-functions`. for example:
+ ```elisp
+ (defvar eldoc-mouse--eldoc-documentation-functions
+ '(eldoc-mouse--eglot-eldoc-documentation-function
+ eldoc-mouse--elisp-eldoc-documentation-function)
+ "The `eldoc-documentation-functions' for `eldoc-mouse-mode'.")
+ ```
+3. submit a pull request. I'd love to merge it.
+
## Requirements
Emacs 30.1 or higher
