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 1e3b0f2: Improve doc strings of project.el Date: Sun, 12 Jul 2020 19:17:11 +0300 Message-ID: <834kqcoghk.fsf@gnu.org> References: <87bllfqj82.fsf@warpmail.net> <831rmavsuq.fsf@gnu.org> <83a70wv4mj.fsf@gnu.org> <5542db0c-cc0d-2743-87ae-7728a0cc94bb@yandex.ru> <83ftaf2rj2.fsf@gnu.org> <43a8f8d4-83fb-f012-8e1d-c1a618b0ef59@yandex.ru> <83mu4m0vub.fsf@gnu.org> <44f2f1f4-ae34-f0bf-b153-f33b8ee6069f@yandex.ru> <83mu4fvjh3.fsf@gnu.org> <7c2e93d4-8d86-bbbb-77a0-bf5d73051907@yandex.ru> <83imf2t4w4.fsf@gnu.org> <95fd893e-0da5-4cdc-a3e8-3c22af750aae@yandex.ru> <837dvfs6wg.fsf@gnu.org> <8bc1f381-248f-5cee-c3c6-a29d411a2f74@yandex.ru> <837dvbphs0.fsf@gnu.org> <83365zp78d.fsf@gnu.org> <831rlipmgg.fsf@gnu.org> <83lfjqnsa6.fsf@gnu.org> <294212ed-5a6e-0a7f-e1c2-97e917f1e6e1@yandex.ru> <83eepgomts.fsf@gnu.org> <83a704okmg.fsf@gnu.org> <5d59dd9b-0848-691a-615e-c16d2070b92d@yandex.ru> <837dv8oida.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="34176"; mail-complaints-to="usenet@ciao.gmane.io" Cc: philip@warpmail.net, theo@thornhill.no, emacs-devel@gnu.org To: dgutov@yandex.ru Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Jul 12 18:17:59 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 1juefu-0008nE-SB for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 18:17:58 +0200 Original-Received: from localhost ([::1]:48408 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1juefs-0003Km-Ss for ged-emacs-devel@m.gmane-mx.org; Sun, 12 Jul 2020 12:17:57 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42676) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1juefJ-0002ub-3h for emacs-devel@gnu.org; Sun, 12 Jul 2020 12:17:21 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:44259) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1juefH-0006JT-HW; Sun, 12 Jul 2020 12:17:19 -0400 Original-Received: from [176.228.60.248] (port=2445 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1juefG-0000lx-N5; Sun, 12 Jul 2020 12:17:19 -0400 In-Reply-To: <837dv8oida.fsf@gnu.org> (message from Eli Zaretskii on Sun, 12 Jul 2020 18:36: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:252881 Archived-At: > Date: Sun, 12 Jul 2020 18:36:33 +0300 > From: Eli Zaretskii > Cc: philip@warpmail.net, theo@thornhill.no, emacs-devel@gnu.org > > > There's nothing hard in understanding what the current code returns: you > > navigate to the function's definition and look at the end. > > Documentation exists so that I won't need to follow a chain of several > functions to find the answer to a simple question. (And no, just > reading the code of project-try-vc is not enough, not unless you know > by heart what each one of the functions it calls does and returns.) Can we approach this from a different angle, please? Can you tell why you are so opposed to having this small piece of information in the doc strings? What harm can it do that you consider unacceptable? I added that piece of information because without it I couldn't wrap my head around what the code does, in particular when it tries to determine which projects are equal to which. I reckon if this was difficult for me, there will be others who could benefit from having that info. I guess you don't have this problem, because you wrote most of that code. But even so, why is it so important not to divulge that information?