From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#71532: [PATCH] 30.0.50; Fix some docstrings in ispell.el Date: Thu, 13 Jun 2024 14:04:18 +0300 Message-ID: <86frthyuh9.fsf@gnu.org> References: Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="35281"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 71532@debbugs.gnu.org To: Arash Esbati Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Jun 13 13:05:11 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1sHiGV-0008tp-E0 for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 13 Jun 2024 13:05:11 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sHiGN-000370-JC; Thu, 13 Jun 2024 07:05:03 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sHiGM-00036s-Ms for bug-gnu-emacs@gnu.org; Thu, 13 Jun 2024 07:05:02 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1sHiGM-0007mf-Dy for bug-gnu-emacs@gnu.org; Thu, 13 Jun 2024 07:05:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1sHiGL-0007gi-Qr for bug-gnu-emacs@gnu.org; Thu, 13 Jun 2024 07:05:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 13 Jun 2024 11:05:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 71532 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 71532-submit@debbugs.gnu.org id=B71532.171827667029454 (code B ref 71532); Thu, 13 Jun 2024 11:05:01 +0000 Original-Received: (at 71532) by debbugs.gnu.org; 13 Jun 2024 11:04:30 +0000 Original-Received: from localhost ([127.0.0.1]:43199 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sHiFp-0007ez-Jf for submit@debbugs.gnu.org; Thu, 13 Jun 2024 07:04:29 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:55142) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sHiFn-0007eb-D3 for 71532@debbugs.gnu.org; Thu, 13 Jun 2024 07:04:27 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sHiFi-0007iG-Kv for 71532@debbugs.gnu.org; Thu, 13 Jun 2024 07:04:22 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=V9hMTjsfJAnPl8fQEJEVrwCIMS9Ij5/W2r1Om1Zvnjk=; b=TTFqaF3mdD8+ dj+CDpMlIrqWt/pnH3qdhpwu7JlkU/nTgL3zoHWh/pHCr2LRYmaaGjEQuCFbWO0QMZ5I1pq7G4EG5 BMreVRDBKnz5UIKML8ZItzLyNCR3R/oIrruQA6biVhCQRu4zJmei6uCIzhObSCYQzvQ8hbJ6lZi1y sqLOmHYOgpoA8IA/bE5RBlwdyHR0sqgnF2htqe/shxqPqdokASx3SPmmjVwBrJx1Lv6TBx1FVqREW V2pdEgJz4oxw2GXhAquLMo2EXLrufapRtqh5exrnbiy8BBWxneSccKJoR/P9XcgPPVkdgLUWMSE0w +9sqBH0xTBQgLTRRJgQ1Lw==; In-Reply-To: (message from Arash Esbati on Thu, 13 Jun 2024 11:51:04 +0200) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:287192 Archived-At: > From: Arash Esbati > 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.