> Please use "If", not "When" in such cases.  "When" has a meaning of
> time, which is not what you mean here.
>
>> +in its @var{action} argument, then @code{display-buffer-alist} can use it
>> +to match a whole category of buffers with different buffer names,
>> +for example:
>> +
>> +@example
>> +@group
>> +(setopt
>> + display-buffer-alist
>> + (cons '((category . comint) (display-buffer-same-window))
>> +        display-buffer-alist))
>> +
>> +(display-buffer (get-buffer-create "*my-shell*")
>> +		'(nil (category . comint)))
>> +@end group
>
> I failed to understand from the description and the example the
> meaning of 'category' in this case.  Specifically, I think the
> description should tell more about the interpretation of the symbol in
> (category . SYMBOL).  The example gives 'comint' as the category
> symbol and says this matches "a whole category of buffers", but
> doesn't explain enough to understand which buffers will match this
> category and which won't.  IOW, the meaning of 'comint' as "category
> of buffers" is not sufficiently explained.

Now this is improved in the patch below.

>> --- a/lisp/subr.el
>> +++ b/lisp/subr.el
>> @@ -7476,6 +7474,8 @@ buffer-match-p
>>    * `major-mode': the buffer matches if the buffer's major mode
>>      is eq to the cons-cell's cdr.  Prefer using `derived-mode'
>>      instead when both can work.
>> +  * `category': the buffer matches if the caller of `display-buffer'
>> +    provided `(category . symbol)' in its ACTION argument.
>
> Same here.  (And "symbol" should be "SYMBOL", upper-case, I think.

Actually symbol is not a function argument here.