[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete
From: |
Juri Linkov |
Subject: |
bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete |
Date: |
Mon, 13 Apr 2020 02:51:17 +0300 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (x86_64-pc-linux-gnu) |
> 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?
- bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete, Juri Linkov, 2020/04/02
- bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete, Dmitry Gutov, 2020/04/02
- bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete, Philipp Stephani, 2020/04/03
- bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete, Juri Linkov, 2020/04/04
- bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete, Eli Zaretskii, 2020/04/09
- bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete, Juri Linkov, 2020/04/11
- bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete, Eli Zaretskii, 2020/04/12
- bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete,
Juri Linkov <=
- bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete, Eli Zaretskii, 2020/04/13
- bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete, Juri Linkov, 2020/04/13