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

From: Arash Esbati <[email-masked]>
Date: Thu, 13 Jun 2024 14:43:43 +0200

Eli Zaretskii <[email-masked]> 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
>From c9776bb6068e0620d2349cf728b37542df40a427 Mon Sep 17 00:00:00 2001
From: Arash Esbati <[email-masked]>
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