[PATCH] dictonary.el documentation

[PATCH] dictonary.el documentation

[No Wayman]

[-- Attachment #1: Type: text/plain, Size: 652 bytes --]


I've attached a patch for what I think are a few improvements to 
dictionary.el's documentation.

There are still a handful of undocumented functions/commands.
The commentary section also redirects to an external source, which 
is not very helpful:

;; You can find more information in the README file of the GitHub
;; repository https://github.com/myrkr/dictionary-el

I bumped into all this when trying out dictionary-tooltip-mode.
I thought "oh, cool", enabled the mode, then...nothing happened.
That's due to the dictionary-tooltip-dictionary defaulting to nil. 
Perhaps this user option could default to 
dictionary-default-dictionary instead. 


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: dictionary.el docs --]
[-- Type: text/x-patch, Size: 3022 bytes --]

From 02c4f83176ab9fb1afdb3962f9b90023961ebaaa Mon Sep 17 00:00:00 2001
From: Nicholas Vollmer <iarchivedmywholelife@gmail.com>
Date: Tue, 23 Jan 2024 09:39:02 -0500
Subject: [PATCH] * lisp/net/dictionary.el: satisfy checkdoc

(dictionary-tool-bar-map): add missing period
(dictionary-process-popup-replies),
(dictionary-read-definition),
(dictionary-display-tooltip): rename ignored parameters
(dictionary-tooltip-track-mouse): describe what function does, not just when
(dictionary-switch-tooltip-mode): reword docstring in terms of ON parameter
---
 lisp/net/dictionary.el | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/lisp/net/dictionary.el b/lisp/net/dictionary.el
index 1981b757017..4f4710a2920 100644
--- a/lisp/net/dictionary.el
+++ b/lisp/net/dictionary.el
@@ -461,7 +461,7 @@ dictionary-tool-bar-map
                                    :vert-only t
                                    :help "Go backwards in history.")
     map)
-  "Like the default `tool-bar-map', but with additions for Dictionary mode")
+  "Like the default `tool-bar-map', but with additions for Dictionary mode.")
 
 ;;;###autoload
 (define-derived-mode dictionary-mode special-mode "Dictionary"
@@ -1316,7 +1316,7 @@ dictionary-popup-matching-words
 			  dictionary-default-popup-strategy
 			  'dictionary-process-popup-replies))
 
-(defun dictionary-process-popup-replies (&ignore)
+(defun dictionary-process-popup-replies (_)
   (let ((list (dictionary-simple-split-string (dictionary-read-answer) "\n+")))
 
     (let ((result (mapcar (lambda (item)
@@ -1360,7 +1360,7 @@ dictionary-definition
 	(dictionary-do-search word dictionary 'dictionary-read-definition t))
     nil))
 
-(defun dictionary-read-definition (&ignore)
+(defun dictionary-read-definition (_)
   (let ((list (dictionary-simple-split-string (dictionary-read-answer) "\n+")))
     (mapconcat #'identity (cdr list) "\n")))
 
@@ -1381,7 +1381,7 @@ dictionary-word-at-mouse-event
 (defvar dictionary-tooltip-mouse-event nil
   "Event that triggered the tooltip mode.")
 
-(defun dictionary-display-tooltip (&ignore)
+(defun dictionary-display-tooltip (_)
   "Search the current word in the `dictionary-tooltip-dictionary'."
   (interactive "e")
   (if (and dictionary-tooltip-mode dictionary-tooltip-dictionary)
@@ -1396,7 +1396,7 @@ dictionary-display-tooltip
     nil))
 
 (defun dictionary-tooltip-track-mouse (event)
-  "Called whenever a dictionary tooltip display is about to be triggered."
+  "Hide current tooltip and setup next tooltip in response to mouse movement EVENT."
   (interactive "e")
   (tooltip-hide)
   (when dictionary-tooltip-mode
@@ -1404,7 +1404,7 @@ dictionary-tooltip-track-mouse
     (tooltip-start-delayed-tip)))
 
 (defun dictionary-switch-tooltip-mode (on)
-  "Turn off or on support for the dictionary tooltip mode.
+  "Turn dictionary tooltip mode off or ON.
 
 It is normally internally called with 1 to enable support for the
 tooltip mode.  The hook function will check the value of the
-- 
2.43.0

Re: [PATCH] dictonary.el documentation

[Philip Kaludercic]

No Wayman <iarchivedmywholelife@gmail.com> writes:


[...]

> -(defun dictionary-read-definition (&ignore)
> +(defun dictionary-read-definition (_)

[...]

Is there any advantage to the one or the other approach?

Re: [PATCH] dictonary.el documentation

[Emanuel Berg]

Philip Kaludercic wrote:

>> -(defun dictionary-read-definition (&ignore)
>> +(defun dictionary-read-definition (_)
>
> Is there any advantage to the one or the other approach?

Shorter to type (shorter lines), less to read, and you can
repeat it with no names attached?

(defun test-ignore (&ignore1 &ignore2 &ignore3)
  1)

(defun test-ignore-2 (_ _ _)
  2)

(defun test-ignore-3 (_a _b _c)
  3)

;; (test-ignore   1 1 1)
;; (test-ignore-2 2 2 2)
;; (test-ignore-3 3 3 3)

-- 
underground experts united
https://dataswamp.org/~incal

Re: [PATCH] dictonary.el documentation

[Stefan Kangas]

No Wayman <iarchivedmywholelife@gmail.com> writes:

> I've attached a patch for what I think are a few improvements to
> dictionary.el's documentation.

Thanks, I have forwarded your patch to the bug tracker, since we tend to
lose track of patches sent to emacs-devel.

Let's continue the discussion there.

Re: [PATCH] dictonary.el documentation

[Stefan Kangas]

Philip Kaludercic <philipk@posteo.net> writes:

> No Wayman <iarchivedmywholelife@gmail.com> writes:
>
>
> [...]
>
>> -(defun dictionary-read-definition (&ignore)
>> +(defun dictionary-read-definition (_)
>
> [...]
>
> Is there any advantage to the one or the other approach?

It is more idiomatic, I think.  AFAICT, the most idiomatic version is to
also say what the argument is:

+(defun dictionary-read-definition (_reply)