bug#34949: 27.0.50; Docstring of `vc-deduce-fileset' incomplete

[Lars Ingebrigtsen]

Philipp Stephani <p.stephani2@gmail.com> writes:

> The docstring of `vc-deduce-fileset' doesn't describe the OBSERVER
> parameter.  It also doesn't explain the meaning of the return values
> FILESET-ONLY-FILES, STATE, and CHECKOUT-MODEL.

The OBSERVER thing is a long-standing issue, and people have added
comments about that parameter for decades.  It now states (incorrectly):

  ;; FIXME: OBSERVER is unused.  The name is not intuitive and is not
  ;; documented.  It's set to t when called from diff and print-log.
  (let (backend)
    (cond
     ((derived-mode-p 'vc-dir-mode)
      (vc-dir-deduce-fileset state-model-only-files))
     ((derived-mode-p 'dired-mode)
      (if observer
          (vc-dired-deduce-fileset)
        (error "State changing VC operations not supported in `dired-mode'")))

But we see that it's used, and used for one thing only: If we call this
function in a dired buffer, the function will signal an error if
OBSERVER is nil.  So all the callers of this function pass in t if it's
a non-state-changing operation.

Or am I reading the code wrong?

So the parameter does make some sense: OBSERVER non-nil means that it's
a non-destructive operation we're doing to do (but we only care in dired
buffers).

Having that check in this function may be a bit odd, but...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no