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: Mon, 27 May 2019 17:54:21 +0300 Message-ID: <6d64213c-75f2-ab84-7ec3-2fee4e3742e0@yandex.ru> 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> 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="169107"; 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 Mon May 27 16:55:11 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 1hVH1q-000ho6-Fu for geb-bug-gnu-emacs@m.gmane.org; Mon, 27 May 2019 16:55:10 +0200 Original-Received: from localhost ([127.0.0.1]:46911 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hVH1p-0001rT-G1 for geb-bug-gnu-emacs@m.gmane.org; Mon, 27 May 2019 10:55:09 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:50472) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hVH1i-0001rB-VC for bug-gnu-emacs@gnu.org; Mon, 27 May 2019 10:55:03 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hVH1h-0000LS-Tn for bug-gnu-emacs@gnu.org; Mon, 27 May 2019 10:55:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:40233) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hVH1h-0000LO-Qh for bug-gnu-emacs@gnu.org; Mon, 27 May 2019 10:55:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hVH1h-0008Di-NU for bug-gnu-emacs@gnu.org; Mon, 27 May 2019 10:55:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Dmitry Gutov Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 27 May 2019 14:55: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.155896887931550 (code B ref 35702); Mon, 27 May 2019 14:55:01 +0000 Original-Received: (at 35702) by debbugs.gnu.org; 27 May 2019 14:54:39 +0000 Original-Received: from localhost ([127.0.0.1]:53774 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hVH1K-0008Cm-PA for submit@debbugs.gnu.org; Mon, 27 May 2019 10:54:39 -0400 Original-Received: from mail-wr1-f42.google.com ([209.85.221.42]:45624) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hVH1I-0008CU-Mt for 35702@debbugs.gnu.org; Mon, 27 May 2019 10:54:37 -0400 Original-Received: by mail-wr1-f42.google.com with SMTP id b18so17152753wrq.12 for <35702@debbugs.gnu.org>; Mon, 27 May 2019 07:54:36 -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=cgahU+jegortqulanHVxn9Bi3wo9nzi62lanJpzLI6Q=; b=Ma2tw9UA+/gk0ytI/lxgz2/GoCxXU1GG/p9hAeT4xEP+rwgQkvjCEMDaWDzLtgJ8ly DZqxkJBkams3VNj+GcpkWfyiQUZyMyk4HFoSVxKKOpMS7yREYG1GvsRfhW20ciVRDQkQ oWsT2UM7rWkza8sfTo9gty94+hVWM/WaK/KRIftMpQNNDPlOyevNO4x9sQATEOA4wMU7 Buzhp9aJP/XDrGPOX9kPZGpOusCqPd0F3DBQnP39JkrhJDQ6QSN4FjLrIGVx8zHpuR5o WXon5KO05GMLvm8QZdOurwtX2r11jR92ucpdBQvcYk+UI3jfag//xnRnCVjITsQKa0EU 9KKQ== 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=cgahU+jegortqulanHVxn9Bi3wo9nzi62lanJpzLI6Q=; b=fZ3esjaYg/IhNLMkVqNc4k90cVqiCdoccgPr4f52t3bEPZarTaPBA4DU5fczfHRFLf p9VSkLvvkYBceCCRcLUI5uFINwn6PvFeL0Rypb0UVZHiUGAHqRB1vVD9NmVCxuEWD7cu 0U6vzMMpvsM3aYWusAPHEFiJskH6FE6BhOp1bVK23vAMgV1n/DTGMetVQjKtbMbnyZ+3 M877TunemB0aig0rhgkCwHn1GKvRQiE8O4Xxk2JaZDZgNbym2mDc3FMqbggDUZ5c1131 bI+Cp1/Lp4Ai65sg0SuFnmxT746kY955G1BvSS+Wqs9xAgNfPg1lfK4ZLSwo+Ga2I+ZA asBw== X-Gm-Message-State: APjAAAWZf+lRTC8wLfc9o6+f0JtV4OTftLx+3U+rapoh2Cl5fELI7jXJ hq7GpVnrJoj81/qIgF8+900= X-Google-Smtp-Source: APXvYqy9F3k5IqgIj6GMwKNE6NQIQrLYRchE2vwVfDsx8Vvp6PI9GDQXz4OCYTh/z5VD6XhYlPns1A== X-Received: by 2002:adf:ee0c:: with SMTP id y12mr50813690wrn.34.1558968869416; Mon, 27 May 2019 07:54:29 -0700 (PDT) Original-Received: from [192.168.0.195] ([109.110.245.170]) by smtp.googlemail.com with ESMTPSA id j206sm16315764wma.47.2019.05.27.07.54.25 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 27 May 2019 07:54:26 -0700 (PDT) In-Reply-To: <83ef4l2mii.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:159813 Archived-At: On 26.05.2019 19:44, Eli Zaretskii wrote: >> It's akin to asking what values could revert-buffer-function have: >> different ones. > > 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. Or for understanding of said code (call the function, show the returned items; call it again if the user wants to refresh the list). All that as long as the function adheres to its protocol. It's like 'cons' in that regard. Or 'seq-map.' 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. > If you want to avoid the (IMO imaginary) danger of > implying there could be no other values, you can say explicitly that > other values are possible. 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. There is some intermediate description in xref--create-fetcher's docstring, though I don't know how much it helped. But if you want a description that goes to the lower level and describes *everything*, like how it uses obarray for Elisp and usually scans the contents of TAGS otherwise... I don't think it's helpful for understanding of the xref--create-fetcher variable, or the corresponding function arguments. It's simply not the appropriate place for it (not sure if an "overview" section would be better, but the manual seems like the best place; we could add some extra commentary in elisp-mode.el or etags.el if the existing ones seem not enough). > IOW, useful documentation should be general, but not too general. If > being general means refraining saying something that could potentially > help the reader understand the software and use it, then you are > probably on the wrong side of "too general". On the other hand, I wouldn't want to bog the description of a fairly clean abstraction (if I do say that myself) with incidental details. Or duplicate information that's already available elsewhere. 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.