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.bugs Subject: bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete Date: Sun, 12 Apr 2020 09:33:24 +0300 Message-ID: <83imi5kybv.fsf@gnu.org> References: <875zfd9lzm.fsf@mail.linkov.net> <87mu8mieve.fsf@mail.linkov.net> <87k13pkxdl.fsf@mail.linkov.net> <207d4e30-aa59-b8eb-c39a-0957757f39eb@yandex.ru> <875zf6cy3w.fsf@mail.linkov.net> <9c39f788-29f1-5a68-c8f3-a4b08ae9ea3b@yandex.ru> <87lfo1dvcf.fsf@mail.linkov.net> <44cda45a-db93-f2c1-626d-9ace68cd6fd1@yandex.ru> <87y2rpqt28.fsf@mail.linkov.net> <874kuci4tx.fsf@mail.linkov.net> <786821a9-ceab-bbe8-b02a-69e77ddde426@yandex.ru> <878sjkjb8p.fsf@mail.linkov.net> <7d73cdd2-6af1-270c-1929-1bf618c304db@yandex.ru> <87tv26pzji.fsf@mail.linkov.net> <979c0191-48ce-f13f-361e-a03b3ff393a6@yandex.ru> <87a73t8rrl.fsf@mail.linkov.net> <87v9me960f.fsf@mail.linkov.net> <83sghdnjaa.fsf@gnu.org> <87d08d3ct2.fsf@mail.linkov.net> Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="67054"; mail-complaints-to="usenet@ciao.gmane.io" Cc: p.stephani2@gmail.com, 34949@debbugs.gnu.org, larsi@gnus.org, dgutov@yandex.ru To: Juri Linkov Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Apr 12 08:34:11 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1jNWC3-000HLA-Cj for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 12 Apr 2020 08:34:11 +0200 Original-Received: from localhost ([::1]:59286 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jNWC2-00005D-4q for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 12 Apr 2020 02:34:10 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60191) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jNWBv-00004s-Hy for bug-gnu-emacs@gnu.org; Sun, 12 Apr 2020 02:34:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jNWBu-0002CL-GT for bug-gnu-emacs@gnu.org; Sun, 12 Apr 2020 02:34:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:45768) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jNWBu-0002CG-De for bug-gnu-emacs@gnu.org; Sun, 12 Apr 2020 02:34:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jNWBu-0004Xd-C2 for bug-gnu-emacs@gnu.org; Sun, 12 Apr 2020 02:34:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 12 Apr 2020 06:34:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 34949 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: confirmed fixed Original-Received: via spool by 34949-submit@debbugs.gnu.org id=B34949.158667323217441 (code B ref 34949); Sun, 12 Apr 2020 06:34:02 +0000 Original-Received: (at 34949) by debbugs.gnu.org; 12 Apr 2020 06:33:52 +0000 Original-Received: from localhost ([127.0.0.1]:57314 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jNWBk-0004XF-A6 for submit@debbugs.gnu.org; Sun, 12 Apr 2020 02:33:52 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:45049) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jNWBi-0004X3-BY for 34949@debbugs.gnu.org; Sun, 12 Apr 2020 02:33:51 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:55709) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1jNWBc-00023I-4x; Sun, 12 Apr 2020 02:33:44 -0400 Original-Received: from [176.228.60.248] (port=3311 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jNWBV-0007u4-6x; Sun, 12 Apr 2020 02:33:43 -0400 In-Reply-To: <87d08d3ct2.fsf@mail.linkov.net> (message from Juri Linkov on Sun, 12 Apr 2020 02:38:01 +0300) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:178222 Archived-At: > From: Juri Linkov > Cc: p.stephani2@gmail.com, larsi@gnus.org, 34949@debbugs.gnu.org, > dgutov@yandex.ru > Date: Sun, 12 Apr 2020 02:38:01 +0300 > > Sorry, I missed these docstrings, so here's a possible patch: No need to be sorry, I'm glad I could help with this. > STATE-MODEL-ONLY-FILES if non-nil, means that the caller needs > -the FILESET-ONLY-FILES STATE and MODEL info. Otherwise, that > -part may be skipped. > +the FILESET-ONLY-FILES, STATE and MODEL info. Otherwise, that > +part may be skipped. Possible values of STATE are explained > +in `vc-state', and MODEL in `vc-checkout-model'. This still doesn't explain what FILESET-ONLY-FILES is, and the MODEL part is spelled CHECKOUT-MODEL in the list shown at the beginning of the doc string. Also, "that part may be skipped" actually means that those elements will not be in the list, and I think "skip" doesn't describe that clearly enough. Here's my take on that doc string (please double-check for accuracy): "Deduce a set of files and a backend to which to apply an operation. Return a list of the form: (BACKEND FILESET FILESET-ONLY-FILES STATE CHECKOUT-MODEL) where the last 3 members are optional, and must be present only if STATE-MODEL-ONLY-FILES is non-nil. NOT-STATE-CHANGING, if non-nil, means that the operation requesting the fileset doesn't intend to change the VC state, such as when printing the log or showing the diffs. If the current buffer is in `vc-dir' or Dired mode, FILESET is the list of marked files, or the current directory if no files are marked. Otherwise, if the current buffer is visiting a version-controlled file, FILESET is a single-file list containing that file's name. Otherwise, if ALLOW-UNREGISTERED is non-nil and the visited file is unregistered, FILESET is a single-file list containing the name of the visited file. Otherwise, throw an error. STATE-MODEL-ONLY-FILES, if non-nil, means that the caller needs the FILESET-ONLY-FILES, STATE, and CHECKOUT-MODEL info. Otherwise, these 3 members may be omitted from the returned list. BEWARE: this function may change the current buffer." Btw, the "change the current buffer" in the last sentence is ambiguous. Does it mean switch to another buffer, or does it mean modify the buffer text? I assume the former, so maybe say "may switch to another buffer" explicitly. Thanks.