From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.bugs Subject: bug#35702: xref revert-buffer Date: Tue, 28 May 2019 17:10:03 +0300 Message-ID: References: <87tvdzv4m2.fsf@mail.linkov.net> <838suw5jvh.fsf@gnu.org> <835zq059az.fsf@gnu.org> <710f0ac1-80d7-6db8-7653-c58f93b6f4ab@yandex.ru> <831s0o54g7.fsf@gnu.org> <9869e4ac-1b36-b605-22a8-b8bab4910132@yandex.ru> <83r28n4pdn.fsf@gnu.org> <2103dba2-60ec-9752-1ab8-71ed66fafe63@yandex.ru> <83h89j3rus.fsf@gnu.org> <28666899-1fcd-947b-8b2d-528f786302a9@yandex.ru> <831s0m4iz1.fsf@gnu.org> <83y32u32eb.fsf@gnu.org> <83ef4l2mii.fsf@gnu.org> <6d64213c-75f2-ab84-7ec3-2fee4e3742e0@yandex.ru> <831s0j3ll9.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="24391"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1 Cc: 35702@debbugs.gnu.org, juri@linkov.net To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue May 28 16:11:17 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hVcov-0006G8-HA for geb-bug-gnu-emacs@m.gmane.org; Tue, 28 May 2019 16:11:17 +0200 Original-Received: from localhost ([127.0.0.1]:35664 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hVcou-0001ql-6R for geb-bug-gnu-emacs@m.gmane.org; Tue, 28 May 2019 10:11:16 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:44640) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hVcon-0001qT-I4 for bug-gnu-emacs@gnu.org; Tue, 28 May 2019 10:11:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hVcol-000868-IP for bug-gnu-emacs@gnu.org; Tue, 28 May 2019 10:11:09 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:43155) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hVcog-000837-68 for bug-gnu-emacs@gnu.org; Tue, 28 May 2019 10:11:07 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hVcog-00073H-0B for bug-gnu-emacs@gnu.org; Tue, 28 May 2019 10:11:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Dmitry Gutov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 28 May 2019 14:11:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 35702 X-GNU-PR-Package: emacs Original-Received: via spool by 35702-submit@debbugs.gnu.org id=B35702.155905261527031 (code B ref 35702); Tue, 28 May 2019 14:11:01 +0000 Original-Received: (at 35702) by debbugs.gnu.org; 28 May 2019 14:10:15 +0000 Original-Received: from localhost ([127.0.0.1]:56699 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hVcnv-00071v-5O for submit@debbugs.gnu.org; Tue, 28 May 2019 10:10:15 -0400 Original-Received: from mail-wr1-f45.google.com ([209.85.221.45]:42517) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hVcnt-00071Z-MU for 35702@debbugs.gnu.org; Tue, 28 May 2019 10:10:14 -0400 Original-Received: by mail-wr1-f45.google.com with SMTP id l2so20407520wrb.9 for <35702@debbugs.gnu.org>; Tue, 28 May 2019 07:10:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=iBzRaAHg/CL+U9nsNGStvhwGJ5hq0a3XRkKLBjx92X8=; b=Y/gBWWNsA3tci8No1jk0wqm+fd/H02xL91WF2vrg9kK1dtQhFafOoL4HKC/3qT8gIy 8ehUw8e5nypA22L2ivqZcoWfx0nqd3Ubb7a2kgUYkosS2p9Ks+u6zIdI8IiAQ556tIfk k4QJvMDc2axmB0Xc+BPubehkqrntezqIogEtH+2c7teGNa02prtH0lQhnJCXuLaqO9Sl KzZHvcbAKM4nOWGW9zxUENnAIA00QHiuis/rIUyqzrxLsgqiXDLveAEPRUG5HRtLWC9o RSxbW4s/vdYlXVDSsyxCdR7KB5BWTNoZSosR8RcaQHAJLBXddfPIy+BTmYafNI922Ic/ p5sg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:cc:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=iBzRaAHg/CL+U9nsNGStvhwGJ5hq0a3XRkKLBjx92X8=; b=h4lAkpJlWR9HyfjPH82B8mdGUkgilJTSrUmItbig3eggc/FP4MCqyA2bg/BvCQcPxK whDhDCWKRQOMD8Lp53iLqmHciz/gK6X/35NkRdlaP9EZBs7So5mHQWotpNNSMaoE1iDM e4sBHb4mJoXM6Aa3hpJbi1YmCZg1/6GTXHuP92L+SVMyG7fpWet1uBaZCXA9uuc/2+EO m88PMAJQEPi3WfNF27zHjTDEXi7mtQYTmWgfgmGpWDYTx13UxVhGEaMDQetZCTMaMqUv UpEV+Ht9W0uWx6J2X0kPirbUvTJo0b9h4FHlasUUMCpPL3xenZWf1WRUdgrdD7lg1k3o SuEQ== X-Gm-Message-State: APjAAAXO4qC9Wk6SWhYRurCbA/a6bwzIhs7117yr5/1nL5eaUkf1NQAz aokRqBDOMPnLJj/0Vpj/MCI= X-Google-Smtp-Source: APXvYqxdCXvVmzIw10J91zC+9RTadBbI/TRRImnJbGWrNtCuj38AmKxFiIegeajf39dxQvi27CVkuQ== X-Received: by 2002:adf:e649:: with SMTP id b9mr32742835wrn.195.1559052607512; Tue, 28 May 2019 07:10:07 -0700 (PDT) Original-Received: from [192.168.0.195] ([109.110.245.170]) by smtp.googlemail.com with ESMTPSA id v13sm2686932wmj.46.2019.05.28.07.10.04 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 28 May 2019 07:10:04 -0700 (PDT) In-Reply-To: <831s0j3ll9.fsf@gnu.org> Content-Language: en-US X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:159849 Archived-At: On 27.05.2019 19:31, Eli Zaretskii wrote: >>> Although in theory there could indeed be an infinite number of values, >>> in practice the current actual set is very small, and can be easily >>> described. >> >> And yet, it's not hugely important to the code that's calling it. > > It was important to me. You prodded me to ask questions and tell you > what made the code reading difficult for me, remember? Now you are > trying to convince me that it isn't a difficulty, or that I shouldn't > be asking for that? I'm sorry to disappoint. I'm sure you understand that there are question I can answer but I'd have hard time converting into code comments. Here are the kinds of questions I was hoping for: * What does this function/variable do, or what is it for? These can translate into [improvements for] docstrings or into top Commentary. * Given the stated purpose of why does it implement it *this particular way*? These can translate into inline comments. As such, I can answer your question (probably already did), but since IMO they are not about xref--fetcher or xref--show-defs, I can't put the answers into nearby comments. So instead I ended up thinking of a few questions along these lines and asking them myself, hence the resulting commit that added some more documentation. >> So previously, we passed a list of xrefs to xref--show-xrefs. Now we >> pass a function that returns said list instead. It's a fairly trivial >> change by itself, so if the previous state of affairs was okay, the new >> one shouldn't require a lot of new documentation. > > You assume that the previous state was okay, which is not a given. > Moreover, you assume that the reader remembers there was a list > before, and can therefore "easily" translate this knowledge to the new > code, instantly understanding that the function now returns the list > that was previously passed as argument. That's a lot of assumptions. Hopefully the new docstrings will make understanding all that easier anyway. >> That depends on the level of detail you would like. The minimal level >> description is in the docstring, and it should be fine for understanding >> any code that uses FETCHER. > > I hope you trust me to have read every bit of comment and doc string I > could possibly find before complaining. Well, there was some extra documentation added in the meantime, and I'm not sure how you feel about it. >> The general way we describe our code could, of course, be improved, but >> I don't subscribe to the idea that we can have a general overview of the >> system no matter where we start reading the code. > > See, I was sure I will get a response like that, which was why I > marked what I wrote as . If you don't intend to humor requests > for more documentation of the code's workings, then why do you respond > to such rants? I did suggest some other places where new commentary can go. Maybe you could propose something else as well, now that I've tried to explain why your previous suggestion is hard for me to do. If I interpreted it correctly, at least.