From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: master c3ab8f1: Improve buffer-match-p documentation Date: Sat, 16 Apr 2022 14:00:28 +0300 Message-ID: <837d7p1eer.fsf@gnu.org> References: <83fsmd1lje.fsf@gnu.org> <87sfqdicbt.fsf@posteo.net> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15259"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Philip Kaludercic Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Apr 16 13:01:45 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nfgBU-0003kG-PO for ged-emacs-devel@m.gmane-mx.org; Sat, 16 Apr 2022 13:01:44 +0200 Original-Received: from localhost ([::1]:49074 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nfgBS-0002iG-ME for ged-emacs-devel@m.gmane-mx.org; Sat, 16 Apr 2022 07:01:42 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:44620) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nfgA1-0001cB-Lp for emacs-devel@gnu.org; Sat, 16 Apr 2022 07:00:13 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:59050) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nfgA1-0002w4-DI; Sat, 16 Apr 2022 07:00:13 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=d/1RwFv4Lqn9bDNjJGkpdAzjgKJbaRsR4tq4hRWoyaI=; b=nBQHSM4gvHga iZmh4j2FrBMuyJCj/QTKK6stjy0Phfnte0wAC8kOMndLkLjcIMKQ+BV3K0Qx+R3yMaiavDh6s1JDj 9beA6O/fQe9xqGzKA1MYy0slLGUbnZkj72q2DNxqK4vbeyJg51QFDjNpr0ceubBOMwulC5T8xG0Nu cy/befQWZuBKcZX3BfI/egRHiDtVdmVj48+DwIzJzCwpCoavVR1JLYLg0f7pE9lp4WKLPjA0tLtbj cJcwFQliCVTOXV0ZkJRO4VyITlpMMhh+YTLN74v/utibdm5UhCQIl7Qo0JMHzDnoreGe5HNCgySYc aeUeb1HF6cVcwacF/cy86Q==; Original-Received: from [87.69.77.57] (port=4490 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nfgA0-0003dj-RO; Sat, 16 Apr 2022 07:00:13 -0400 In-Reply-To: <87sfqdicbt.fsf@posteo.net> (message from Philip Kaludercic on Sat, 16 Apr 2022 09:53:26 +0000) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:288479 Archived-At: > From: Philip Kaludercic > Cc: emacs-devel@gnu.org > Date: Sat, 16 Apr 2022 09:53:26 +0000 > > Eli Zaretskii writes: > > >> +** New function 'buffer-match-p' > >> +Check if a buffer matches a condition, specified using a DSL. > > > > A "DSL"? what's that? We don't have that acronym anywhere else in > > Emacs, AFAICS. Please make that entry more self-explanatory. > > It is supposed to mean "Domain Specific Language". I never noticed that > it wasn't used anywhere else, so sorry about that. Then again I wasn't > sure how else to put it. What about > > Can be used to check if buffers satisfy a possibly complex > condition, [giving a few examples] Just "satisfies some conditions" (with examples) should be fine, IMO. > > Since buffer-match-p is not documented in the manual, I think this > > change is for the worse, as it leaves CONDITIONS undocumented. Or am > > I missing something? > > No, I haven't written that yet. This should best be documented in > lispref/buffers.texi, right? Probably in "Buffer List", yes. > >> -(defun display-buffer-assq-regexp (buffer-name alist action) > >> +(defun display-buffer-assq-regexp (buffer-or-name alist action) > >> "Retrieve ALIST entry corresponding to BUFFER-NAME. > >> -This returns the cdr of the alist entry ALIST if either its key > >> -satisfied a BUFFER-NAME per `buffer-match'. ACTION should have > >> -the form of the action argument passed to `display-buffer'." > >> +This returns the cdr of the alist entry ALIST if key and > >> +buffer-or-name satisfy `buffer-match-p'. ACTION should have the > >> +form of the action argument passed to `display-buffer'." > > > > I fixed some minor issues with the modified doc string, but that still > > leaves one question unanswered: what does this function return if no > > alist entry satisfies buffer-match-p? That should be documented. > > ... If no entry is found, nil is returned? That's fine, but please avoid passive tense. Something like If no matching entry is found in ALIST, return nil.