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 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix. Date: Mon, 13 Jul 2020 16:21:51 +0300 Message-ID: <83tuybmtxs.fsf@gnu.org> References: <20200712184908.13140.5739@vcs0.savannah.gnu.org> <20200712184909.BBC61209B1@vcs0.savannah.gnu.org> <7bf4d6ef-c0ec-43dc-ad5d-f6e81422ad90@yandex.ru> <83zh84m5ws.fsf@gnu.org> <3dd1c224-69b2-40af-5b2e-43a310253632@yandex.ru> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="14827"; 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 Mon Jul 13 15:22:32 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 1juyPf-0003ju-6Q for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 15:22:31 +0200 Original-Received: from localhost ([::1]:57808 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1juyPe-0000R1-79 for ged-emacs-devel@m.gmane-mx.org; Mon, 13 Jul 2020 09:22:30 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:49092) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1juyP9-0008N5-9H for emacs-devel@gnu.org; Mon, 13 Jul 2020 09:21:59 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:35720) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1juyP8-00083V-Fv; Mon, 13 Jul 2020 09:21:58 -0400 Original-Received: from [176.228.60.248] (port=4435 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1juyP8-0006Jm-0I; Mon, 13 Jul 2020 09:21:58 -0400 In-Reply-To: <3dd1c224-69b2-40af-5b2e-43a310253632@yandex.ru> (message from Dmitry Gutov on Mon, 13 Jul 2020 14:09:54 +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:252913 Archived-At: > Cc: emacs-devel@gnu.org > From: Dmitry Gutov > Date: Mon, 13 Jul 2020 14:09:54 +0300 > > >> except for those that are ignored > >> in the default 'project-ignores' implementation. > >> > >> But this is basically a tautology. If we wanted to describe transient's > >> particular behavior we'd have to describe what it actually ignores (and > >> it honors vc-directory-exclusion-list as well as > >> grep-find-ignored-files). But that pretty clunky for one docstring. > > > > Which is why I just mentioned the function which implements all that. > > Thing is, it's a generic function. It has multiple implementations, so > saying 'per project-ignores' is not very informative. What I wrote talks only about the "transient" project, which AFAIU uses the default implementation. So I think it's as informative as possible in this case. But if you can come up with a better wording which doesn't lose useful information, please do. Btw, your implementation style makes it unusually hard to write good doc strings. I'm not quite sure why, but one possible reason is that IMO you bring the generics too high, too close to the application level, where doc strings should be more and more user-oriented. When this is coupled with your reluctance, to say the least, to disclose details of what you consider to be opaque objects, it becomes hard to say anything useful about many functions, because describing what functions do usually involves talking about their inputs and outputs, and how the former are processed into the latter. The "for example" method that I tried to use was about the only technique I could think of to overcome those difficulties, and you reject even that. Whether one agrees with your coding style or not, the difficulties it presents to documenting our code are real, and I suggest that you consider this disadvantage seriously, because it basically flies in the face of long-standing traditions of Emacs self-documenting features. > > You cannot usefully refer to the default implementation without saying > > that this or that types of project use the default implementation, > > which is IMO against your information encapsulation policies. > > I think I see the reason for your choice. But I'm saying we can describe > the behavior of project-ignores for that value. Feel free to propose such a description, if you think such details are important for a transient object. > Like we already described the behavior of 'project-root' for that value > earlier in the same sentence ("denotes a project rooted in that directory"). That is actually quite vague. It gives you some idea what such a project means, but if you take it apart, it is just a fancy way of saying that this project knows where its root is, and nothing else. > While in general we might not want the consumers of project-current > depend on particular behavior of either of these generic functions when > using backends retrieved in the "normal" way, this is a special, > fallback case that can inform the user of the behavior of said fallback > backend. If we had a better place to describe that behavior in, though, > we could move that there. The description of the transient project doesn't have to be detailed, because it's, well, transient. Its documentation needs to give some idea what it is and how it is used; anything else is not a necessity, IMO.