bug#37771: 26.3; doc for `dired-auto-revert-buffer'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> Please consider improving the doc so that it does the following:
>
> * Explains what is meant by "visiting" a Dired buffer.  The Emacs
>   manuals and other doc only speak about visiting a file in a buffer.
>   Just what constitutes "visiting" a Dired buffer?  It seems like it's
>   sufficient to display the buffer and select its window.  Is that it?

It means whatever Emacs means by "visiting" a file.  I don't see what's
there to explain.

> * Explains the Value Menu items in Customize - in particular, item
>   `Revert changed Dired buffer'.

Explaining what "revert" means in this context seems a bit odd.  There's
a manual for that.

> * Explains that the option has no effect on Dired buffers containing
>   arbitrary file lists (i.e., whose DIRNAME is a cons).  It is relevant
>   only for actual directory listings.

You mean that switching it off doesn't stop reverting in that case?

              ;; Always revert when `dir-or-list' is a cons.  Also revert
              ;; if `dired-directory' is a cons but `dir-or-list' is not.
              ((or (consp dir-or-list) (consp dired-directory))
               (setq dired-directory dir-or-list)
               (revert-buffer))
              ;; Always revert regardless of whether it has changed or not.
              ((eq dired-auto-revert-buffer t)
               (revert-buffer))

As far as I can tell, this is only reached when you call `dired'
explicitly with a list of file names?  That dired updates the buffer
when you call it with a bunch of file names, without consulting
dired-auto-revert-buffer, seems pretty self-evident.

> * Lists the Lisp values that correspond to the Value Menu items.

They all seem documented?

          (const :tag "Revert changed Dired buffer" dired-directory-changed-p)

is just a predicate function.

Didn't see anything that needed fixing here, and I'm closing this bug
report.

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