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 15:44:10 +0300 Message-ID: <83r1ubxm1x.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> Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="70126"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 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 14:45:10 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 1jmGOL-000I9G-NI for ged-emacs-devel@m.gmane-mx.org; Fri, 19 Jun 2020 14:45:09 +0200 Original-Received: from localhost ([::1]:43948 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jmGOK-0005JS-NK for ged-emacs-devel@m.gmane-mx.org; Fri, 19 Jun 2020 08:45:08 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:36562) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jmGNa-0004s1-Rj for emacs-devel@gnu.org; Fri, 19 Jun 2020 08:44:22 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:44922) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jmGNZ-0005nI-To; Fri, 19 Jun 2020 08:44:21 -0400 Original-Received: from [176.228.60.248] (port=4539 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jmGNZ-0005sA-Fc; Fri, 19 Jun 2020 08:44:21 -0400 In-Reply-To: <41c3e63e-7006-c89d-0812-643731a88d39@yandex.ru> (message from Dmitry Gutov on Fri, 19 Jun 2020 15:30:33 +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:252346 Archived-At: > Cc: emacs-devel@gnu.org > From: Dmitry Gutov > Date: Fri, 19 Jun 2020 15:30:33 +0300 > > On 19.06.2020 14:24, Eli Zaretskii wrote: > > > Feel free to suggest a correction. > > My suggested correction would be the previous wording. It might have > been more vague, but it covered both cases. 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, it is IMO wrong to make a doc string too vague because there's some difficulty in saying something accurately and yet succinctly enough. We should look for solutions that don't leave our doc strings too vague. > > "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? Armed with that knowledge, I could suggest a more accurate doc string that still tells enough to understand what the command does. Thanks.