GNU bug report logs - #30202
27.0.50; Code refactoring on assq-delete-all assoc-delete-all

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Tino Calancha <tino.calancha <at> gmail.com>
Cc: 30202 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: bug#30202: 27.0.50; Code refactoring on assq-delete-all assoc-delete-all
Date: Tue, 23 Jan 2018 18:05:16 +0200

> From: Tino Calancha <tino.calancha <at> gmail.com>
> Date: Tue, 23 Jan 2018 09:02:12 +0900 (JST)
> cc: Tino Calancha <tino.calancha <at> gmail.com>, 30202 <at> debbugs.gnu.org, 
>     monnier <at> iro.umontreal.ca
> 
> Updated the patch with the NEWS entry and manual doc.

Thanks, a few nits below.

> +@defun assoc-delete-all key alist &optional test
> +This function is like @code{assq-delete-all} except that accepts
                                                ^^^^^^^^^^^^^^^^^^^
"... except that it accepts"

> +an optional argument @var{test} to compare the keys in @var{alist}.

To make it even more clear, I would say

  except that it accepts an optional argument @var{test}, a predicate
  function to compare the keys in @var{alist}.

> +@var{test} defaults to @code{equal}.

An even more minor nit: try to avoid starting a sentence with @var.
In an Info manual, @var produces UPPER CASE, which looks OK at the
beginning of a sentence; but in the printed manual, @var produces a
lower-case word in slant typeface, which makes the sentence begin with
a lower-case letter.  So it is better to either say

  If omitted or @code{nil}, @var{test} defaults to ...

or even make it part of the previous sentence:

  ... a predicate function to compare the keys in @var{alist};
  @var{test} defaults to @code{equal}.

Or maybe even toss the reference to TEST:

  ... a predicate function to compare the keys in @var{alist}; if
  omitted, it defaults to @code{equal}.

(And yes, I know that our manuals are full of sentences starting with
@var; something to improve on, I guess.)

Thanks!

Previous Next

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