bug#67053: 29.1; Doc string of variable `dired-use-ls-dired'

[Drew Adams <drew.adams@oracle.com>]

> > Perhaps I'm misunderstanding something?  If so, please make the doc
> > string clearer to avoid such misunderstanding.
> 
> AFAIU in your case this check is never performed (because
> `ls-lisp-use-insert-directory-program' defaults to nil in your case).

Yes.

> The doc is not really wrong because "This is performed the first time
> `dired-insert-directory' is invoked." is just never for you.

1. I don't see that the check never being performed
makes that doc, as written, any clearer, or that
understanding that doc depends on the check being
performed or on function `dired-insert-directory'
being invoked.

Understanding the actual behavior on MS Windows does
depend on the check (not) being performed, but that's
the code, not the doc.

2. (a) Yes, `ls-lisp-use-insert-directory-program'
is nil in my case, but (b) `dired-insert-directory'
_is_ invoked.

Debugger entered--entering a function:
* dired-insert-directory("z:/foo/bar/toto/bbbbb/" "-al" nil nil t)
  ^^^^^^^^^^^^^^^^^^^^^^
  dired-readin-insert()
  #f(compiled-function () #<bytecode -0xc727057c68a81bd>)()
  combine-change-calls-1(1 1 #f(compiled-function ...))
  dired-readin()
  dired-internal-noselect("z:/foo/bar/toto/bbbbb/" nil)
  dired-noselect("~/toto/bbbbb" nil)
  #f(compiled-function (dirname &optional switches) ...
  ls-lisp--dired(#f(compiled-function ...
  apply(ls-lisp--dired #f(compiled-function ...
  dired("~/toto/bbbbb" nil)
  funcall-interactively(dired "~/toto/bbbbb" nil)
  command-execute(dired)

The _check of `dired-use-ls-dired'_ is never done by
`dired-insert-directory', because this test is nil:

  (not (and (featurep 'ls-lisp)
       (null ls-lisp-use-insert-directory-program)))

This doesn't clarify that doc, IMO.  It does, however,
mean that the part you quoted is incorrect - the doc
_is_ really wrong.

When `ls-lisp-use-insert-directory-program' is nil,
not only does the check not occur the first time
`dired-insert-directory' is invoked, but it's _never_
performed.

In short, `dired-use-ls-dired' isn't used if option
`ls-lisp-use-insert-directory-program' is nil; it's
irrelevant in that case.  The doc should say that.