Re: master c3ab8f1: Improve buffer-match-p documentation

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: emacs-devel@gnu.org
> Date: Sat, 16 Apr 2022 23:11:59 +0000
> 
> Before I push something I should fix, I'll attach my proposed changes
> here:

Thanks.

> +@defun buffer-match-p condition buffer-or-name arg
> +This function can be used to check if a buffer designated by

I'd drop "can be used", because that's the function's purpose.
Instead, I'd say "This function checks whether a buffer...".

> +                                                     An optional third
> +argument @code{arg} can be passed on to predicate functions.

Another unnecessary "can".  Suggest to rephrase:

  Optional third argument @var{arg} is passed to the predicate
  function in @var{condition}.

This also means you should have &optional in the @defun line:

  @defun buffer-match-p condition buffer-or-name &optional arg

> +                                                              A
> +predicate can be one of the following:

This suddenly starts talking about "predicates" out of the blue, when
the function's argument is named "condition".  So something is missing
here to connect between the two.

> +@itemize @bullet{}
> +@item
> +A string containing a regular expression.

"Containing"?  I think you mean to say "A string that is interpreted
as a regular expression".

> +A function that is passed the buffer, and is satisfied if the function
> +returns a non-nil value.  The first argument is always the buffer, and
> +if the function accepts two arguments (as per @code{func-arity}), the
> +third argument to @code{buffer-match-p} will be passed on to the
> +predicate function.

I would suggest

  A function, which should return non-@code{nil} if the buffer
  matches.  If the function expects one argument, it is called with
  @var{buffer-or-name} as the argument; if it expects 2 arguments, the
  first argument is @var{buffer-or-name} and the second is @var{arg}
  (or @code{nil} if @var{arg} is omitted).

> +@item
> +A cons-cell @code{(TYPE . DATA)} where @code{TYPE} is one of

Instead of UPPER-CASE that we use in Lisp doc strings, in Texinfo we
use @var{lower-case}.

Also, I don't think TYPE and DATA are good labels for what you
describe below.  How about OPER and EXPR instead?

> +@defun match-buffers condition buffer-list arg

&optional is missing.

> +This function returns a list of all buffers that satisfy a
> +@code{condition}, as defined for @code{buffer-match-p}.  By default
> +all buffers are considered, but this can be restricted via the second
> +optional @code{buffer-list} argument.  Optionally, a third argument
> +@code{arg} is passed on to @code{buffer-match-p}.

The last sentence is better rephrased as

  Optional third argument @var{arg} will be used by @var{condition} in
  the same way as @code{buffer-match-p} does.

>  ** New function 'buffer-match-p'
> -Check if a buffer matches a condition, specified using a DSL.
> +Check if a buffer satisfies some condition.  Some examples for
> +conditions can be regular expressions that match a buffer name, a
> +cons-cell like (major-mode . shell-mode) that matches any buffer where
> +major-mode is shell-mode or a combined with a condition like (and
> +"\\`\\*.+\\*\\'" (major-mode . special-mode)).

Please capitalize "major-mode" and "special-mode", as those stand for
something else.