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

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> 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.

I cannot object to any of this, and have made the changes.

>>  ** 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.

I am not sure I follow you, (major-mode . special-mode) is a condition
that checks if a buffer derives from `special-mode'.  If capitalised, it
wouldn't do what it should (or rather it would just be ignored).

-- 
        Philip Kaludercic