From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: master 1e3b0f2: Improve doc strings of project.el Date: Fri, 19 Jun 2020 17:07:28 +0300 Message-ID: <83pn9vxi73.fsf@gnu.org> References: <20200619075401.21856.16524@vcs0.savannah.gnu.org> <20200619075402.CE1D220A27@vcs0.savannah.gnu.org> <243920e8-f660-fac9-00d6-1bcecde91e39@yandex.ru> <831rmbz4ak.fsf@gnu.org> <41c3e63e-7006-c89d-0812-643731a88d39@yandex.ru> <83r1ubxm1x.fsf@gnu.org> <46c34dab-c95f-45ea-50ee-f0e023a70e74@yandex.ru> Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="60322"; mail-complaints-to="usenet@ciao.gmane.io" Cc: philip@warpmail.net, emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jun 19 16:09:34 2020 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 1jmHi2-000FaB-0Q for ged-emacs-devel@m.gmane-mx.org; Fri, 19 Jun 2020 16:09:34 +0200 Original-Received: from localhost ([::1]:42482 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jmHi1-0008BH-3c for ged-emacs-devel@m.gmane-mx.org; Fri, 19 Jun 2020 10:09:33 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59370) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jmHgE-0006P8-2t for emacs-devel@gnu.org; Fri, 19 Jun 2020 10:07:42 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:46579) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jmHgC-0003dR-U1; Fri, 19 Jun 2020 10:07:40 -0400 Original-Received: from [176.228.60.248] (port=1676 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jmHgC-0002T8-2p; Fri, 19 Jun 2020 10:07:40 -0400 In-Reply-To: <46c34dab-c95f-45ea-50ee-f0e023a70e74@yandex.ru> (message from Dmitry Gutov on Fri, 19 Jun 2020 15:54:56 +0300) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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:252352 Archived-At: > Cc: emacs-devel@gnu.org, "Philip K." > From: Dmitry Gutov > Date: Fri, 19 Jun 2020 15:54:56 +0300 > > > That'd be a step backwards, IMO. I changed the doc string because in > > its original form it didn't tell me enough to understand which buffers > > could and couldn't be selected by that command. > > In general, those would be the buffers where (project-current) would > return the current project. I think that's pretty unambiguous. That's the implementation, but it cannot be used to make the doc string useful, at least not directly. It tells you what is the test for whether a particular buffer is eligible for the switch, but the doc string should instead tell up front what are the general traits of all the eligible buffers. IOW, the user should understand which of the buffers he or she can switch to with this command. > >>> "Buffer in a current project" > >>> sounds too vague at best to me: a project doesn't include any buffers. > >> > >> It includes their default-directory-es. Any idea how to modify the > >> docstring that the first sentence still fits on one line? > > > > What kind of buffers are those, in normal use? IOW, what buffers are > > relevant to the project, but don't visit any file/directory? > > If you look at bug#41868, it mentions VC-Dir and Dired buffers. Perhaps > Philip also has other examples. So will something like the below do the job? Switch to another buffer related to the current project. A buffer is related to a project if its `default-directory' is inside the directory hierarchy of the project's root. Btw, AFAIU this command can prompt for a project's root, but the doc string doesn't mention that important fact. > It also cleans up some "invisible" buffers created to service the files > in the project, such as ones created by Flymake, etc. By "it" what do you mean here? you don't mean project-switch-to-buffer, do you? And if so, how is that related to the issue at hand, which is the doc string of that function?