GNU bug report logs - #71532
[PATCH] 30.0.50; Fix some docstrings in ispell.el

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 71532 in the body.
You can then email your comments to 71532 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Arash Esbati <arash <at> gnu.org>
To: "emacs-bugs" <bug-gnu-emacs <at> gnu.org>
Subject: [PATCH] 30.0.50; Fix some docstrings in ispell.el
Date: Thu, 13 Jun 2024 11:51:04 +0200

[Message part 1 (text/plain, inline)]

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

[0001-Fix-some-docstrings.patch (text/x-patch, attachment)]

Message #8 received at 71532 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Arash Esbati <arash <at> gnu.org>
Cc: 71532 <at> debbugs.gnu.org
Subject: Re: bug#71532: [PATCH] 30.0.50; Fix some docstrings in ispell.el
Date: Thu, 13 Jun 2024 14:04:18 +0300

> From: Arash Esbati <arash <at> 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.

Message #11 received at 71532 <at> debbugs.gnu.org (full text, mbox):

From: Arash Esbati <arash <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 71532 <at> debbugs.gnu.org
Subject: Re: bug#71532: [PATCH] 30.0.50; Fix some docstrings in ispell.el
Date: Thu, 13 Jun 2024 14:43:43 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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

[0001-Fix-some-docstrings.-bug-71532.patch (text/x-patch, attachment)]

Message #16 received at 71532-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Arash Esbati <arash <at> gnu.org>
Cc: 71532-done <at> debbugs.gnu.org
Subject: Re: bug#71532: [PATCH] 30.0.50; Fix some docstrings in ispell.el
Date: Sat, 15 Jun 2024 15:03:15 +0300

> From: Arash Esbati <arash <at> gnu.org>
> Cc: 71532 <at> debbugs.gnu.org
> Date: Thu, 13 Jun 2024 14:43:43 +0200
> 
> Eli Zaretskii <eliz <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.