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

Previous Next

Full log

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Juri Linkov <juri <at> linkov.net>
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: Sun, 12 Apr 2020 09:33:24 +0300

> From: Juri Linkov <juri <at> linkov.net>
> Cc: p.stephani2 <at> gmail.com,  larsi <at> gnus.org,  34949 <at> debbugs.gnu.org,
>   dgutov <at> 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.

Previous Next

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