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

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Arash Esbati <arash <at> gnu.org>
Cc: 71532 <at> debbugs.gnu.org
Subject: 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.

Previous Next

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