GNU bug report logs - #34949
27.0.50; Docstring of `vc-deduce-fileset' incomplete

Previous Next

Full log

Message #209 received at 34949 <at> debbugs.gnu.org (full text, mbox):

From: Juri Linkov <juri <at> linkov.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: p.stephani2 <at> gmail.com, 34949 <at> debbugs.gnu.org, larsi <at> gnus.org,
 dgutov <at> yandex.ru
Subject: Re: bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete
Date: Mon, 13 Apr 2020 02:51:17 +0300

> 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.

Everything is correct, I couldn't have said it better myself.

>   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.

Correct, this means switching to another buffer.

The only thing I don't see in your fixed docstring are the references
to possible values in `vc-state' and `vc-checkout-model'.  Are they needed?

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.