bug#71532: [PATCH] 30.0.50; Fix some docstrings in ispell.el

bug#71532: [PATCH] 30.0.50; Fix some docstrings in ispell.el

[Arash Esbati]

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

Hi all,

please find attached a trivial patch fixing some docstrings in
ispell.el.  `checkdoc-minor-mode' reports more, but I didn't try to
understand the code in order to fix the rest as well.

Best, Arash

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-some-docstrings.patch --]
[-- Type: text/x-patch, Size: 3676 bytes --]

From cdf1fcacca5dab0e1277f901a86d4b9e334c71ca Mon Sep 17 00:00:00 2001
From: Arash Esbati <arash@gnu.org>
Date: Thu, 13 Jun 2024 11:46:09 +0200
Subject: [PATCH] ; Fix some docstrings.

---
 lisp/textmodes/ispell.el | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/lisp/textmodes/ispell.el b/lisp/textmodes/ispell.el
index f523df9881e..3c8ed1d30d7 100644
--- a/lisp/textmodes/ispell.el
+++ b/lisp/textmodes/ispell.el
@@ -219,8 +219,9 @@ ispell-alternate-dictionary
   :type '(choice file (const :tag "None" nil)))
 
 (defcustom ispell-complete-word-dict nil
-  "Plain word-list dictionary used for word completion if
-different from `ispell-alternate-dictionary'.
+  "Plain word-list dictionary used for word completion.
+This word-list is used if it is different from
+`ispell-alternate-dictionary'.
 This is also used by `ispell-lookup-words' and `ispell-complete-word'."
   :type '(choice file (const :tag "None" nil)))
 
@@ -639,8 +640,8 @@ ispell-dicts-name2locale-equivs-alist
     ("slovenian"     "sl_SI")
     ("svenska"       "sv_SE")
     ("hebrew"        "he_IL"))
-  "Alist with known matching locales for standard dict names in
-`ispell-dictionary-base-alist'.")
+  "Alist with known matching locales for standard dict names.
+Standard dict names are defined in `ispell-dictionary-base-alist'.")
 
 
 ;;; **********************************************************************
@@ -759,14 +760,16 @@ ispell-with-safe-default-directory
      ,@body))
 
 (defun ispell-call-process (&rest args)
-  "Like `call-process', but defend against bad `default-directory'."
+  "Like `call-process', but defend against bad `default-directory'.
+ARGS are passed to `call-process'."
   (ispell-with-safe-default-directory
-    (apply 'call-process args)))
+    (apply #'call-process args)))
 
 (defun ispell-call-process-region (&rest args)
-  "Like `call-process-region', but defend against bad `default-directory'."
+  "Like `call-process-region', but defend against bad `default-directory'.
+ARGS are passed to `call-process'."
   (ispell-with-safe-default-directory
-    (apply 'call-process-region args)))
+    (apply #'call-process-region args)))
 
 (defvar ispell-debug-buffer)
 
@@ -856,10 +859,9 @@ ispell-get-aspell-config-value
     (car (split-string (buffer-string)))))
 
 (defun ispell-aspell-find-dictionary (dict-name)
-  "For Aspell dictionary DICT-NAME, return a list of parameters if an
-associated data file is found or nil otherwise.  List format is that
-of `ispell-dictionary-base-alist' elements."
-
+  "For Aspell dictionary DICT-NAME, return a list of parameters or nil.
+List format is that of `ispell-dictionary-base-alist' elements if an
+associated data file is found."
   ;; Make sure `ispell-aspell-dict-dir' is defined
   (or ispell-aspell-dict-dir
       (setq ispell-aspell-dict-dir
@@ -1607,8 +1609,8 @@ ispell-parsing-keyword
 The last occurring definition in the buffer will be used.")
 
 (defun ispell--\\w-filter (char)
-  "Return CHAR in a string when CHAR doesn't have \"word\" syntax,
-nil otherwise.  CHAR must be a character."
+  "Return CHAR in a string when CHAR doesn't have \"word\" syntax or nil.
+CHAR must be a character."
   (let ((str (string char)))
     (and
      (not (string-match "\\w" str))
@@ -3868,7 +3870,8 @@ ispell-message-text-end
 
 
 (defun ispell-mime-multipartp (&optional limit)
-  "Return multipart message start boundary or nil if none."
+  "Return multipart message start boundary or nil if none.
+LIMIT is passed to `re-search-forward', which see."
   ;; caller must ensure `case-fold-search' is set to t
   (and
    (re-search-forward
-- 
2.45.2

bug#71532: [PATCH] 30.0.50; Fix some docstrings in ispell.el

[Eli Zaretskii]

> From: Arash Esbati <arash@gnu.org>
> Date: Thu, 13 Jun 2024 11:51:04 +0200
> 
> please find attached a trivial patch fixing some docstrings in
> ispell.el.

Thanks, see some comments below.

> `checkdoc-minor-mode' reports more, but I didn't try to
> understand the code in order to fix the rest as well.

Please show the messages if you have them handy.

>  (defun ispell-aspell-find-dictionary (dict-name)
> -  "For Aspell dictionary DICT-NAME, return a list of parameters if an
> -associated data file is found or nil otherwise.  List format is that
> -of `ispell-dictionary-base-alist' elements."
> -
> +  "For Aspell dictionary DICT-NAME, return a list of parameters or nil.
> +List format is that of `ispell-dictionary-base-alist' elements if an
> +associated data file is found."

This is hard to grasp, and the first sentence is also confusing (the
"or nil" part is not easy to interpret).  Please try to find a better
wording.

>  (defun ispell--\\w-filter (char)
> -  "Return CHAR in a string when CHAR doesn't have \"word\" syntax,
> -nil otherwise.  CHAR must be a character."
> +  "Return CHAR in a string when CHAR doesn't have \"word\" syntax or nil.
> +CHAR must be a character."

I couldn't parse this doc string.  It is not clear what it returns,
and it is not clear what does "or nil" refer to.  The last sentence
should probably say "CHAR must be a valid character."

>  (defun ispell-mime-multipartp (&optional limit)
> -  "Return multipart message start boundary or nil if none."
> +  "Return multipart message start boundary or nil if none.

This sentence uses the so-called "construct state" of 4 words, which
is a bad idea in English, because the result is very confusing.  I
would reword:

  Return the start boundary of a multipart message, or nil if none.

bug#71532: [PATCH] 30.0.50; Fix some docstrings in ispell.el

[Arash Esbati]

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

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, see some comments below.

Thanks for your comments, next try is attached.

> Please show the messages if you have them handy.

--8<---------------cut here---------------start------------->8---
*** ispell.el: checkdoc-start
ispell.el:172: There should be two spaces after a period
ispell.el:652: Argument ‘interactivep’ should appear (as INTERACTIVEP) in the doc string
ispell.el:1522: All variables and subroutines might as well have a documentation string
ispell.el:1524: All variables and subroutines might as well have a documentation string
ispell.el:1526: All variables and subroutines might as well have a documentation string
ispell.el:1528: All variables and subroutines might as well have a documentation string
ispell.el:1531: All variables and subroutines might as well have a documentation string
ispell.el:1534: All variables and subroutines might as well have a documentation string
ispell.el:1539: All variables and subroutines might as well have a documentation string
ispell.el:1899: Argument ‘region’ should appear (as REGION) in the doc string
ispell.el:2049: Argument ‘extra-otherchars’ should appear (as EXTRA-OTHERCHARS) in the doc string
ispell.el:2121: Argument ‘no-query’ should appear (as NO-QUERY) in the doc string
ispell.el:2148: Lisp symbol ‘query-replace’ should appear in quotes
ispell.el:2433: Some lines are over 80 columns wide
ispell.el:2605: Argument ‘output’ should appear (as OUTPUT) in the doc string
ispell.el:2710: All variables and subroutines might as well have a documentation string
ispell.el:3024: Argument ‘arg’ should appear (as ARG) in the doc string
ispell.el:3091: Argument ‘reg-start’ should appear (as REG-START) in the doc string
ispell.el:3346: Argument ‘start’ should appear (as START) in the doc string
ispell.el:3425: Argument ‘start’ should appear (as START) in the doc string
ispell.el:3445: All variables and subroutines might as well have a documentation string
ispell.el:3898: Argument ‘boundary’ should appear (as BOUNDARY) in the doc string
ispell.el:3982: Keycode C-c embedded in doc string.  Use \\<mapvar> & \\[command] instead
ispell.el:4116: All variables and subroutines might as well have a documentation string
--8<---------------cut here---------------end--------------->8---

Best, Arash

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-some-docstrings.-bug-71532.patch --]
[-- Type: text/x-patch, Size: 3727 bytes --]

From c9776bb6068e0620d2349cf728b37542df40a427 Mon Sep 17 00:00:00 2001
From: Arash Esbati <arash@gnu.org>
Date: Thu, 13 Jun 2024 11:46:09 +0200
Subject: [PATCH] ; Fix some docstrings.  (bug#71532)

---
 lisp/textmodes/ispell.el | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/lisp/textmodes/ispell.el b/lisp/textmodes/ispell.el
index f523df9881e..d803670e104 100644
--- a/lisp/textmodes/ispell.el
+++ b/lisp/textmodes/ispell.el
@@ -219,8 +219,9 @@ ispell-alternate-dictionary
   :type '(choice file (const :tag "None" nil)))
 
 (defcustom ispell-complete-word-dict nil
-  "Plain word-list dictionary used for word completion if
-different from `ispell-alternate-dictionary'.
+  "Plain word-list dictionary used for word completion.
+This word-list is used if it is different from
+`ispell-alternate-dictionary'.
 This is also used by `ispell-lookup-words' and `ispell-complete-word'."
   :type '(choice file (const :tag "None" nil)))
 
@@ -639,8 +640,8 @@ ispell-dicts-name2locale-equivs-alist
     ("slovenian"     "sl_SI")
     ("svenska"       "sv_SE")
     ("hebrew"        "he_IL"))
-  "Alist with known matching locales for standard dict names in
-`ispell-dictionary-base-alist'.")
+  "Alist with known matching locales for standard dict names.
+Standard dict names are defined in `ispell-dictionary-base-alist'.")
 
 
 ;;; **********************************************************************
@@ -759,14 +760,16 @@ ispell-with-safe-default-directory
      ,@body))
 
 (defun ispell-call-process (&rest args)
-  "Like `call-process', but defend against bad `default-directory'."
+  "Like `call-process', but defend against bad `default-directory'.
+ARGS are passed to `call-process'."
   (ispell-with-safe-default-directory
-    (apply 'call-process args)))
+    (apply #'call-process args)))
 
 (defun ispell-call-process-region (&rest args)
-  "Like `call-process-region', but defend against bad `default-directory'."
+  "Like `call-process-region', but defend against bad `default-directory'.
+ARGS are passed to `call-process'."
   (ispell-with-safe-default-directory
-    (apply 'call-process-region args)))
+    (apply #'call-process-region args)))
 
 (defvar ispell-debug-buffer)
 
@@ -856,10 +859,9 @@ ispell-get-aspell-config-value
     (car (split-string (buffer-string)))))
 
 (defun ispell-aspell-find-dictionary (dict-name)
-  "For Aspell dictionary DICT-NAME, return a list of parameters if an
-associated data file is found or nil otherwise.  List format is that
-of `ispell-dictionary-base-alist' elements."
-
+  "For Aspell dictionary DICT-NAME, return a list of parameters.
+List format is that of `ispell-dictionary-base-alist' elements.  Return
+nil if no associated data file is found."
   ;; Make sure `ispell-aspell-dict-dir' is defined
   (or ispell-aspell-dict-dir
       (setq ispell-aspell-dict-dir
@@ -1607,8 +1609,8 @@ ispell-parsing-keyword
 The last occurring definition in the buffer will be used.")
 
 (defun ispell--\\w-filter (char)
-  "Return CHAR in a string when CHAR doesn't have \"word\" syntax,
-nil otherwise.  CHAR must be a character."
+  "Return CHAR as a string when CHAR doesn't have \"word\" syntax.
+CHAR must be a valid character.  Return nil otherwise."
   (let ((str (string char)))
     (and
      (not (string-match "\\w" str))
@@ -3868,7 +3870,8 @@ ispell-message-text-end
 
 
 (defun ispell-mime-multipartp (&optional limit)
-  "Return multipart message start boundary or nil if none."
+  "Return the start boundary of a multipart message, or nil if none.
+LIMIT is passed to `re-search-forward', which see."
   ;; caller must ensure `case-fold-search' is set to t
   (and
    (re-search-forward
-- 
2.45.2

bug#71532: [PATCH] 30.0.50; Fix some docstrings in ispell.el

[Eli Zaretskii]

> From: Arash Esbati <arash@gnu.org>
> Cc: 71532@debbugs.gnu.org
> Date: Thu, 13 Jun 2024 14:43:43 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Thanks, see some comments below.
> 
> Thanks for your comments, next try is attached.

Installed, with a slight fix.

> > Please show the messages if you have them handy.
> 
> --8<---------------cut here---------------start------------->8---
> *** ispell.el: checkdoc-start

Thanks, I tried to fix those.