Fix the effects and documentation of 'dired-free-space'

* lisp/dired.el (dired-free-space): Fix doc string and Custom tags.
(dired--insert-disk-space): When 'dired-free-space' is 'separate',
return the position of the beginning of the disk-space line, to be
compatible with pre-Emacs 29 behavior under
'dired-hide-details-mode'.  (Bug#65186)

* doc/emacs/dired.texi (Misc Dired Features): Fix wording in
documentation of 'dired-free-space'.

1 files changed, 16 insertions, 8 deletions

diff --git a/lisp/dired.el b/lisp/dired.el
index d0af05d68f0..4c2e9243e6c 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -218,14 +218,19 @@ If t, they are marked if and as the files linked to were marked.
 If a character, new links are unconditionally marked with that character.")
 
 (defcustom dired-free-space 'first
-  "Whether and how to display the amount of free disk space in Dired buffers.
+  "Whether and how to display the disk space usage info in Dired buffers.
 If nil, don't display.
-If `separate', display on a separate line (along with used count).
-If `first', display only the free disk space on the first line,
-following the directory name."
-  :type '(choice (const :tag "On a separate line" separate)
-                 (const :tag "On the first line, after directory name" first)
-                 (const :tag "Don't display" nil))
+If `separate', display on a separate line, and include both the used
+and the free disk space.
+If `first', the default, display only the free disk space on the first
+line, following the directory name."
+  :type '(choice (const
+                  :tag
+                  "On separate line, display both used and free space" separate)
+                 (const
+                  :tag
+                  "On first line, after directory name, display only free space" first)
+                 (const :tag "Don't display disk space usage" nil))
   :version "29.1"
   :group 'dired)
 
@@ -1769,7 +1774,10 @@ see `dired-use-ls-dired' for more details.")
          ((eq dired-free-space 'separate)
 	  (end-of-line)
 	  (insert " available " available)
-          (forward-line 1)
+          ;; The separate free-space line is considered part of the
+          ;; directory content, for the purposes of
+          ;; 'dired-hide-details-mode'.
+          (beginning-of-line)
           (point))
          ((eq dired-free-space 'first)
           (goto-char beg)