bug-gnu-emacs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#30202: 27.0.50; Code refactoring on assq-delete-all assoc-delete-all


From: Eli Zaretskii
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@gmail.com>
> Date: Tue, 23 Jan 2018 09:02:12 +0900 (JST)
> cc: Tino Calancha <tino.calancha@gmail.com>, 30202@debbugs.gnu.org, 
>     monnier@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!





reply via email to

[Prev in Thread] Current Thread [Next in Thread]