bug#47957: diredx-aux doctrings [PATCH INCLUDED]

bug#47957: diredx-aux doctrings [PATCH INCLUDED]

[Boruch Baum]

[-- Attachment #1: Type: text/plain, Size: 236 bytes --]

File dired-aux.el had many docstrings in comment form, meaning that they
were non discoverable using `describe-function'. The attached patch
fixes that.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

[-- Attachment #2: dired-aux.patch --]
[-- Type: text/x-diff, Size: 25311 bytes --]

diff --git a/dired-aux.el b/dired-aux.el
index 3ee877e..dd5c27d 100644
--- a/dired-aux.el
+++ b/dired-aux.el
@@ -314,12 +314,12 @@ List has a form of (file-name full-file-name (attribute-list))."
 ;;; Change file attributes

 (defun dired-do-chxxx (attribute-name program op-symbol arg)
-  ;; Change file attributes (group, owner, timestamp) of marked files and
-  ;; refresh their file lines.
-  ;; ATTRIBUTE-NAME is a string describing the attribute to the user.
-  ;; PROGRAM is the program used to change the attribute.
-  ;; OP-SYMBOL is the type of operation (for use in `dired-mark-pop-up').
-  ;; ARG describes which files to use, as in `dired-get-marked-files'.
+  "Change file attributes (group, owner, timestamp).
+Operates on marked files and refresh their file lines.
+ATTRIBUTE-NAME is a string describing the attribute to the user.
+PROGRAM is the program used to change the attribute. OP-SYMBOL is
+the type of operation (for use in `dired-mark-pop-up'). ARG
+describes which files to use, as in `dired-get-marked-files'."
   (let* ((files (dired-get-marked-files t arg nil nil t))
 	 ;; The source of default file attributes is the file at point.
 	 (default-file (dired-get-filename t t))
@@ -458,11 +458,11 @@ into the minibuffer."
   (interactive "P")
   (dired-do-chxxx "Timestamp" dired-touch-program 'touch arg))

-;; Process all the files in FILES in batches of a convenient size,
-;; by means of (FUNCALL FUNCTION ARGS... SOME-FILES...).
-;; Batches are chosen to need less than MAX chars for the file names,
-;; allowing 3 extra characters of separator per file name.
 (defun dired-bunch-files (max function args files)
+"Process all the files in FILES in batches of a convenient size.
+Uses (FUNCALL FUNCTION ARGS... SOME-FILES...). Batches are
+chosen to need less than MAX chars for the file names, allowing 3
+extra characters of separator per file name."
   (let (pending
 	past
 	(pending-length 0)
@@ -594,8 +594,8 @@ with a prefix argument."
 ;;; Subroutines of dired-clean-directory.

 (defun dired-map-dired-file-lines (fun)
-  ;; Perform FUN with point at the end of each non-directory line.
-  ;; FUN takes one argument, the absolute filename.
+"Perform FUN with point at the end of each non-directory line.
+FUN takes one argument, the absolute filename."
   (save-excursion
     (let (file buffer-read-only)
       (goto-char (point-min))
@@ -815,13 +815,14 @@ prompted for the shell command to use interactively."
   "Separates marked files in dired shell commands.")

 (defun dired-shell-stuff-it (command file-list on-each &optional _raw-arg)
-;; "Make up a shell command line from COMMAND and FILE-LIST.
-;; If ON-EACH is t, COMMAND should be applied to each file, else
-;; simply concat all files and apply COMMAND to this.
-;; FILE-LIST's elements will be quoted for the shell."
-;; Might be redefined for smarter things and could then use RAW-ARG
-;; (coming from interactive P and currently ignored) to decide what to do.
-;; Smart would be a way to access basename or extension of file names.
+"Make up a shell command line from COMMAND and FILE-LIST.
+If ON-EACH is t, COMMAND should be applied to each file, else
+simply concat all files and apply COMMAND to this.
+FILE-LIST's elements will be quoted for the shell.
+
+Might be redefined for smarter things and could then use RAW-ARG
+(coming from interactive P and currently ignored) to decide what to do.
+Smart would be a way to access basename or extension of file names."
   (let* ((in-background (string-match "[ \t]*&[ \t]*\\'" command))
 	 (command (if in-background
 		      (substring command 0 (match-beginning 0))
@@ -961,20 +962,21 @@ With a prefix argument, kill that many lines starting with the current line.
 ;;;###autoload
 (defun dired-do-kill-lines (&optional arg fmt)
   "Kill all marked lines (not the files).
-With a prefix argument, kill that many lines starting with the current line.
-\(A negative argument kills backward.)
+With a prefix argument, kill that many lines starting with the
+current line. A negative argument kills backward.

 If you use this command with a prefix argument to kill the line
 for a file that is a directory, which you have inserted in the
 Dired buffer as a subdirectory, then it deletes that subdirectory
 from the buffer as well.

-To kill an entire subdirectory \(without killing its line in the
-parent directory), go to its directory header line and use this
+To kill an entire subdirectory without killing its line in the
+parent directory, go to its directory header line and use this
 command with a prefix argument (the value does not matter).

-To undo the killing, the undo command can be used as normally."
-  ;; Returns count of killed lines.  FMT="" suppresses message.
+To undo the killing, the undo command can be used as normally.
+
+Returns count of killed lines.  FMT=\"\" suppresses message."
   (interactive "P")
   (if arg
       (if (dired-get-subdir)
@@ -1000,8 +1002,8 @@ To undo the killing, the undo command can be used as normally."
 ;;;###begin dired-cp.el

 (defun dired-compress ()
-  ;; Compress or uncompress the current file.
-  ;; Return nil for success, offending filename else.
+"Compress or uncompress the current file.
+Return nil for success, offending filename else."
   (let* (buffer-read-only
 	 (from-file (dired-get-filename))
 	 (new-file (dired-compress-file from-file)))
@@ -1206,11 +1208,11 @@ Return nil if no change in files."
                   (concat file ".Z"))))))))
 \f
 (defun dired-mark-confirm (op-symbol arg)
-  ;; Request confirmation from the user that the operation described
-  ;; by OP-SYMBOL is to be performed on the marked files.
-  ;; Confirmation consists in a y-or-n question with a file list
-  ;; pop-up unless OP-SYMBOL is a member of `dired-no-confirm'.
-  ;; The files used are determined by ARG (as in dired-get-marked-files).
+"Request confirmation from the user for an operation on marked-files.
+The operation is described by OP-SYMBOL. Confirmation consists in
+a y-or-n question with a file list pop-up unless OP-SYMBOL is a
+member of `dired-no-confirm'. The files used are determined by
+ARG (as in dired-get-marked-files)."
   (or (eq dired-no-confirm t)
       (memq op-symbol dired-no-confirm)
       ;; Pass t for DISTINGUISH-ONE-MARKED so that a single file which
@@ -1224,19 +1226,19 @@ Return nil if no change in files."
 				   (dired-mark-prompt arg files) "? ")))))

 (defun dired-map-over-marks-check (fun arg op-symbol &optional show-progress)
-;  "Map FUN over marked files (with second ARG like in dired-map-over-marks)
-; and display failures.
+ "Map FUN over marked files and display failures.
+Second ARG is as in function `dired-map-over-marks'.

-; FUN takes zero args.  It returns non-nil (the offending object, e.g.
-; the short form of the filename) for a failure and probably logs a
-; detailed error explanation using function `dired-log'.
+FUN takes zero args.  It returns non-nil (the offending object, e.g.
+the short form of the filename) for a failure and probably logs a
+detailed error explanation using function `dired-log'.

-; OP-SYMBOL is a symbol describing the operation performed (e.g.
-; `compress').  It is used with `dired-mark-pop-up' to prompt the user
-; (e.g. with `Compress * [2 files]? ') and to display errors (e.g.
-; `Failed to compress 1 of 2 files - type W to see why ("foo")')
+OP-SYMBOL is a symbol describing the operation performed (e.g.
+`compress').  It is used with `dired-mark-pop-up' to prompt the user
+(e.g. with `Compress * [2 files]? ') and to display errors (e.g.
+`Failed to compress 1 of 2 files - type W to see why ("foo")')

-; SHOW-PROGRESS if non-nil means redisplay dired after each file."
+SHOW-PROGRESS if non-nil means redisplay dired after each file."
   (if (dired-mark-confirm op-symbol arg)
       (let* ((total-list;; all of FUN's return values
 	      (dired-map-over-marks (funcall fun) arg show-progress))
@@ -1299,7 +1301,8 @@ uncompress and unpack all the files in the archive."
 ;; Commands for Emacs Lisp files - load and byte compile

 (defun dired-byte-compile ()
-  ;; Return nil for success, offending file name else.
+  "Byte-compile file at POINT.
+Return nil for success; otherwise, the offending file name."
   (let* ((filename (dired-get-filename))
 	 elc-file buffer-read-only failure)
     (condition-case err
@@ -1325,7 +1328,8 @@ uncompress and unpack all the files in the archive."
   (dired-map-over-marks-check #'dired-byte-compile arg 'byte-compile t))

 (defun dired-load ()
-  ;; Return nil for success, offending file name else.
+  "Load file at POINT.
+Return nil for success; otherwise, the offending file name."
   (let ((file (dired-get-filename)) failure)
     (condition-case err
       (load file nil nil t)
@@ -1390,11 +1394,11 @@ See Info node `(emacs)Subdir switches' for more details."
   (revert-buffer))
 \f
 (defun dired-update-file-line (file)
-  ;; Delete the current line, and insert an entry for FILE.
-  ;; If FILE is nil, then just delete the current line.
-  ;; Keeps any marks that may be present in column one (doing this
-  ;; here is faster than with dired-add-entry's optional arg).
-  ;; Does not update other dired buffers.  Use dired-relist-entry for that.
+"Delete the current line, and insert an entry for FILE.
+If FILE is nil, then just delete the current line. Keeps any
+marks that may be present in column one (doing this here is
+faster than with dired-add-entry's optional arg). Does not update
+other dired buffers. Use dired-relist-entry for that."
   (let* ((opoint (line-beginning-position))
          (char (char-after opoint))
          (buffer-read-only))
@@ -1533,10 +1537,9 @@ files matching `dired-omit-regexp'."
     t))

 (defun dired-after-subdir-garbage (dir)
-  ;; Return pos of first file line of DIR, skipping header and total
-  ;; or wildcard lines.
-  ;; Important: never moves into the next subdir.
-  ;; DIR is assumed to be unhidden.
+  "Return pos of first file line of DIR.
+Header lines and total or wildcard lines are skipped. Important:
+never moves into the next subdir. DIR is assumed to be unhidden."
   (save-excursion
     (or (dired-goto-subdir dir) (error "This cannot happen"))
     (forward-line 1)
@@ -1562,8 +1565,8 @@ See `dired-delete-file' in case you wish that."
 			    #'dired-relist-entry file))

 (defun dired-relist-entry (file)
-  ;; Relist the line for FILE, or just add it if it did not exist.
-  ;; FILE must be an absolute file name.
+  "Relist the line for FILE, or just add it if it did not exist.
+FILE must be an absolute file name."
   (let (buffer-read-only marker)
     ;; If cursor is already on FILE's line delete-region will cause
     ;; save-excursion to fail because of floating makers,
@@ -1587,15 +1590,15 @@ Special value `always' suppresses confirmation."
 		 (other :tag "ask" t))
   :group 'dired)

-;; This is a fluid var used in dired-handle-overwrite.  It should be
-;; let-bound whenever dired-copy-file etc are called.  See
-;; dired-create-files for an example.
-(defvar dired-overwrite-confirmed)
+(defvar dired-overwrite-confirmed
+  "A fluid var used in dired-handle-overwrite.
+It should be let-bound whenever dired-copy-file etc are called.
+See `dired-create-files' for an example.")

 (defun dired-handle-overwrite (to)
-  ;; Save old version of file TO that is to be overwritten.
-  ;; `dired-overwrite-confirmed' and `overwrite-backup-query' are fluid vars
-  ;; from dired-create-files.
+"Save old version of file TO that is to be overwritten.
+`dired-overwrite-confirmed' and `overwrite-backup-query' are
+fluid vars from dired-create-files."
   (let (backup)
     (when (and dired-backup-overwrite
 	       dired-overwrite-confirmed
@@ -1712,8 +1715,8 @@ unless OK-IF-ALREADY-EXISTS is non-nil."
       (setq blist (cdr blist)))))

 (defun dired-rename-subdir-1 (dir to)
-  ;; Rename DIR to TO in headerlines and dired-subdir-alist, if DIR or
-  ;; one of its subdirectories is expanded in this buffer.
+"Rename DIR to TO in header lines and dired-subdir-alist, if DIR
+or one of its subdirectories is expanded in this buffer."
   (let ((expanded-dir (expand-file-name dir))
 	(alist dired-subdir-alist)
 	(elt nil))
@@ -1747,10 +1750,10 @@ unless OK-IF-ALREADY-EXISTS is non-nil."
 	  (dired-advertise)))))

 (defun dired-rename-subdir-2 (elt dir to)
-  ;; Update the headerline and dired-subdir-alist element, as well as
-  ;; dired-switches-alist element, of directory described by
-  ;; alist-element ELT to reflect the moving of DIR to TO.  Thus, ELT
-  ;; describes either DIR itself or a subdir of DIR.
+  "Update the headerline and dired-subdir-alist element, as well
+as dired-switches-alist element, of directory described by
+alist-element ELT to reflect the moving of DIR to TO. Thus, ELT
+describes either DIR itself or a subdir of DIR."
   (save-excursion
     (let ((regexp (regexp-quote (directory-file-name dir)))
 	  (newtext (directory-file-name to))
@@ -2007,17 +2010,16 @@ Optional arg HOW-TO determines how to treat the target.
 	 (lambda (_from) target))
        marker-char))))

-;; Read arguments for a marked-files command that wants a file name,
-;; perhaps popping up the list of marked files.
-;; ARG is the prefix arg and indicates whether the files came from
-;; marks (ARG=nil) or a repeat factor (integerp ARG).
-;; If the current file was used, the list has but one element and ARG
-;; does not matter. (It is non-nil, non-integer in that case, namely '(4)).
-;; DEFAULT is the default value to return if the user just hits RET;
-;; if it is omitted or nil, then the name of the directory is used.
-
 (defun dired-mark-read-file-name (prompt dir op-symbol arg files
 					 &optional default)
+  "Read arguments for a marked-files command that wants a file name,
+perhaps popping up the list of marked files. ARG is the prefix
+arg and indicates whether the files came from marks (ARG=nil) or
+a repeat factor (integerp ARG). If the current file was used, the
+list has but one element and ARG does not matter. (It is non-nil,
+non-integer in that case, namely '(4)). DEFAULT is the default
+value to return if the user just hits RET; if it is omitted or
+nil, then the name of the directory is used."
   (dired-mark-pop-up
    nil op-symbol files
    #'read-file-name
@@ -2029,7 +2031,7 @@ Optional arg HOW-TO determines how to treat the target.
     (dired-dwim-target-next)))

 (defun dired-dwim-target-next (&optional all-frames)
-  ;; Return directories from all next windows with dired-mode buffers.
+  "Return directories from all next windows with dired-mode buffers."
   (mapcan (lambda (w)
             (with-current-buffer (window-buffer w)
               (when (eq major-mode 'dired-mode)
@@ -2039,12 +2041,12 @@ Optional arg HOW-TO determines how to treat the target.
                                    'nomini all-frames))))

 (defun dired-dwim-target-next-visible ()
-  ;; Return directories from all next visible windows with dired-mode buffers.
+  "Return directories from all next visible windows with dired-mode buffers."
   (dired-dwim-target-next 'visible))

 (defun dired-dwim-target-recent ()
-  ;; Return directories from all visible windows with dired-mode buffers
-  ;; ordered by most-recently-used.
+  "Return directories from all visible windows with dired-mode
+buffers ordered by most-recently-used."
   (mapcar #'cdr (sort (mapcan (lambda (w)
                                 (with-current-buffer (window-buffer w)
                                   (when (eq major-mode 'dired-mode)
@@ -2055,9 +2057,9 @@ Optional arg HOW-TO determines how to treat the target.
                       (lambda (a b) (> (car a) (car b))))))

 (defun dired-dwim-target-directory ()
-  ;; Try to guess which target directory the user may want.
-  ;; If there is a dired buffer displayed in one of the next windows,
-  ;; use its current subdir, else use current subdir of this dired buffer.
+  "Try to guess which target directory the user may want.
+If there is a dired buffer displayed in one of the next windows,
+use its current subdir, else use current subdir of this dired buffer."
   (let ((this-dir (and (eq major-mode 'dired-mode)
 		       (dired-current-directory))))
     ;; non-dired buffer may want to profit from this function, e.g. vm-uudecode
@@ -2066,16 +2068,16 @@ Optional arg HOW-TO determines how to treat the target.
       this-dir)))

 (defun dired-dwim-target-defaults (fn-list target-dir)
-  ;; Return a list of default values for file-reading functions in Dired.
-  ;; This list may contain directories from Dired buffers in other windows.
-  ;; `fn-list' is a list of file names used to build a list of defaults.
-  ;; When nil or more than one element, a list of defaults will
-  ;; contain only directory names.  `target-dir' is a directory name
-  ;; to exclude from the returned list, for the case when this
-  ;; directory name is already presented in initial input.
-  ;; For Dired operations that support `dired-dwim-target',
-  ;; the argument `target-dir' should have the value returned
-  ;; from `dired-dwim-target-directory'.
+  "Return a list of default values for file-reading functions in Dired.
+This list may contain directories from Dired buffers in other windows.
+`fn-list' is a list of file names used to build a list of defaults.
+When nil or more than one element, a list of defaults will
+contain only directory names.  `target-dir' is a directory name
+to exclude from the returned list, for the case when this
+directory name is already presented in initial input.
+For Dired operations that support `dired-dwim-target',
+the argument `target-dir' should have the value returned
+from `dired-dwim-target-directory'."
   (let ((dired-one-file
 	 (and (consp fn-list) (null (cdr fn-list)) (car fn-list)))
 	(current-dir (and (eq major-mode 'dired-mode)
@@ -2265,14 +2267,14 @@ of `dired-dwim-target', which see."

 (defun dired-do-create-files-regexp
   (file-creator operation arg regexp newname &optional whole-name marker-char)
-  ;; Create a new file for each marked file using regexps.
-  ;; FILE-CREATOR and OPERATION as in dired-create-files.
-  ;; ARG as in dired-get-marked-files.
-  ;; Matches each marked file against REGEXP and constructs the new
-  ;;   filename from NEWNAME (like in function replace-match).
-  ;; Optional arg WHOLE-NAME means match/replace the whole file name
-  ;;   instead of only the non-directory part of the file.
-  ;; Optional arg MARKER-CHAR as in dired-create-files.
+  "Create a new file for each marked file using regexps.
+FILE-CREATOR and OPERATION as in dired-create-files.
+ARG as in dired-get-marked-files.
+Matches each marked file against REGEXP and constructs the new
+  filename from NEWNAME (like in function replace-match).
+Optional arg WHOLE-NAME means match/replace the whole file name
+  instead of only the non-directory part of the file.
+Optional arg MARKER-CHAR as in dired-create-files."
   (let* ((fn-list (dired-get-marked-files nil arg))
 	 (operation-prompt (concat operation " `%s' to `%s'?"))
 	 (rename-regexp-help-form (format-message "\
@@ -2317,8 +2319,8 @@ Type SPC or `y' to %s one match, DEL or `n' to skip to next,
      file-creator operation fn-list regexp-name-constructor marker-char)))

 (defun dired-mark-read-regexp (operation)
-  ;; Prompt user about performing OPERATION.
-  ;; Read and return list of: regexp newname arg whole-name.
+  "Prompt user about performing OPERATION.
+Read and return list of: regexp newname arg whole-name."
   (let* ((whole-name
 	  (equal 0 (prefix-numeric-value current-prefix-arg)))
 	 (arg
@@ -2385,9 +2387,9 @@ See function `dired-do-rename-regexp' for more info."

 (defun dired-create-files-non-directory
   (file-creator basename-constructor operation arg)
-  ;; Perform FILE-CREATOR on the non-directory part of marked files
-  ;; using function BASENAME-CONSTRUCTOR, with query for each file.
-  ;; OPERATION like in dired-create-files, ARG as in dired-get-marked-files.
+  "Perform FILE-CREATOR on the non-directory part of marked files
+using function BASENAME-CONSTRUCTOR, with query for each file.
+OPERATION like in dired-create-files, ARG as in dired-get-marked-files."
   (let (rename-non-directory-query)
     (dired-create-files
      file-creator
@@ -2477,10 +2479,11 @@ If it is already present, overwrite the previous entry;
 With a prefix arg, you may edit the `ls' switches used for this listing.
   You can add `R' to the switches to expand the whole tree starting at
   this subdirectory.
-This function takes some pains to conform to `ls -lR' output."
-  ;; NO-ERROR-IF-NOT-DIR-P needed for special filesystems like
-  ;; Prospero where dired-ls does the right thing, but
-  ;; file-directory-p has not been redefined.
+This function takes some pains to conform to `ls -lR' output.
+
+NO-ERROR-IF-NOT-DIR-P is needed for special filesystems like
+Prospero where dired-ls does the right thing, but
+file-directory-p has not been redefined."
   (interactive
    (list (dired-get-filename)
 	 (if current-prefix-arg
@@ -2526,8 +2529,8 @@ This function takes some pains to conform to `ls -lR' output."
     (restore-buffer-modified-p modflag)))

 (defun dired-insert-subdir-validate (dirname &optional switches)
-  ;; Check that it is valid to insert DIRNAME with SWITCHES.
-  ;; Signal an error if invalid (e.g. user typed `i' on `..').
+  "Check that it is valid to insert DIRNAME with SWITCHES.
+Signal an error if invalid (e.g. user typed `i' on `..')."
   (or (dired-in-this-tree-p dirname (expand-file-name default-directory))
       (error  "%s: not in this directory tree" dirname))
   (let ((real-switches (or switches dired-subdir-switches)))
@@ -2543,12 +2546,12 @@ This function takes some pains to conform to `ls -lR' output."
 	 '("F" "b"))))))

 (defun dired-alist-add (dir new-marker)
-  ;; Add new DIR at NEW-MARKER.  Sort alist.
+  "Add new DIR at NEW-MARKER.  Sort alist."
   (dired-alist-add-1 dir new-marker)
   (dired-alist-sort))

 (defun dired-alist-sort ()
-  ;; Keep the alist sorted on buffer position.
+  "Keep the alist sorted on buffer position."
   (setq dired-subdir-alist
 	(sort dired-subdir-alist
 	      (lambda (elt1 elt2)
@@ -2575,7 +2578,7 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
     m-alist))

 (defun dired-insert-subdir-newpos (new-dir)
-  ;; Find pos for new subdir, according to tree order.
+  "Find pos for new subdir, according to tree order."
   ;;(goto-char (point-max))
   (let ((alist dired-subdir-alist) elt dir new-pos)
     (while alist
@@ -2594,8 +2597,8 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
   (point))

 (defun dired-insert-subdir-del (element)
-  ;; Erase an already present subdir (given by ELEMENT) from buffer.
-  ;; Move to that buffer position.  Return a mark-alist.
+  "Erase an already present subdir (given by ELEMENT) from buffer.
+Move to that buffer position.  Return a mark-alist."
   (let ((begin-marker (cdr element)))
     (goto-char begin-marker)
     ;; Are at beginning of subdir (and inside it!).  Now determine its end:
@@ -2607,8 +2610,8 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
       (delete-region begin-marker (point)))))

 (defun dired-insert-subdir-doinsert (dirname switches)
-  ;; Insert ls output after point.
-  ;; Return the boundary of the inserted text (as list of BEG and END).
+  "Insert ls output after point.
+Return the boundary of the inserted text (as list of BEG and END)."
   (save-excursion
     (let ((begin (point)))
       (let ((dired-actual-switches
@@ -2643,14 +2646,15 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
 	    (run-hooks 'dired-after-readin-hook))))))

 (defun dired-tree-lessp (dir1 dir2)
-  ;; Lexicographic order on file name components, like `ls -lR':
-  ;; DIR1 < DIR2 if DIR1 comes *before* DIR2 in an `ls -lR' listing,
-  ;;   i.e., if DIR1 is a (grand)parent dir of DIR2,
-  ;;   or DIR1 and DIR2 are in the same parentdir and their last
-  ;;   components are string-lessp.
-  ;; Thus ("/usr/" "/usr/bin") and ("/usr/a/" "/usr/b/") are tree-lessp.
-  ;; string-lessp could arguably be replaced by file-newer-than-file-p
-  ;;   if dired-actual-switches contained t.
+  "Lexicographic order on file name components, like `ls -lR':
+DIR1 < DIR2 if DIR1 comes *before* DIR2 in an `ls -lR' listing,
+i.e., if DIR1 is a (grand)parent dir of DIR2, or DIR1 and DIR2
+are in the same parentdir and their last components are
+string-lessp.
+
+Thus (\"/usr/\" \"/usr/bin\") and (\"/usr/a/\" \"/usr/b/\") are
+tree-lessp. `string-lessp' could arguably be replaced by
+`file-newer-than-file-p' if dired-actual-switches contained t."
   (setq dir1 (file-name-as-directory dir1)
 	dir2 (file-name-as-directory dir2))
   (let ((components-1 (dired-split "/" dir1))

bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED]

[Drew Adams]

Thanks for doing this.

A minor suggestion (for consideration) for
`dired-do-kill-lines', based on my feeling
that "kill" here is a misleading misnomer:

Say "remove", not "kill" (which generally
has to do with removing text and placing it
on the kill ring).

FWIW, I have this doc string for it in
Dired+.  Apart from the added optional arg
INIT-COUNT, the behavior is the same.
___

Remove all marked lines, or the next ARG lines.
The files or directories on those lines are _not_ deleted.  Only the
Dired listing is affected.  To restore the removals, use `M-x revert-buffer'.

With a numeric prefix arg, remove that many lines going forward,
starting with the current line.  (A negative prefix arg removes lines
going backward.)

If you use a prefix arg to remove the line for a subdir whose listing
you have inserted into the Dired buffer, then that subdir listing is
also removed.

To remove a subdir listing _without_ removing the subdir's line in its
parent listing, go to the header line of the subdir listing and use
this command with any prefix arg.

When called from Lisp, non-nil INIT-COUNT is added to the number of
lines removed by this invocation, for the reporting message.
___

(Also, don't forget to prefix lines that start with ( with \.)

bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED]

[Boruch Baum]

[-- Attachment #1: Type: text/plain, Size: 457 bytes --]

On 2021-04-22 20:15, Drew Adams wrote:
> Thanks for doing this.

Quite welcome. Let's see what it takes to get merged...

> A minor suggestion (for consideration) for `dired-do-kill-lines'
> ...
> Say "remove", not "kill" (which generally has to do with removing
> ...
> (Also, don't forget to prefix lines that start with ( with \.)

Done. Updated patch attached.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

[-- Attachment #2: dired-aux-2.patch --]
[-- Type: text/x-diff, Size: 25311 bytes --]

diff --git a/dired-aux.el b/dired-aux.el
index 3ee877e..dd5c27d 100644
--- a/dired-aux.el
+++ b/dired-aux.el
@@ -314,12 +314,12 @@ List has a form of (file-name full-file-name (attribute-list))."
 ;;; Change file attributes

 (defun dired-do-chxxx (attribute-name program op-symbol arg)
-  ;; Change file attributes (group, owner, timestamp) of marked files and
-  ;; refresh their file lines.
-  ;; ATTRIBUTE-NAME is a string describing the attribute to the user.
-  ;; PROGRAM is the program used to change the attribute.
-  ;; OP-SYMBOL is the type of operation (for use in `dired-mark-pop-up').
-  ;; ARG describes which files to use, as in `dired-get-marked-files'.
+  "Change file attributes (group, owner, timestamp).
+Operates on marked files and refresh their file lines.
+ATTRIBUTE-NAME is a string describing the attribute to the user.
+PROGRAM is the program used to change the attribute. OP-SYMBOL is
+the type of operation (for use in `dired-mark-pop-up'). ARG
+describes which files to use, as in `dired-get-marked-files'."
   (let* ((files (dired-get-marked-files t arg nil nil t))
 	 ;; The source of default file attributes is the file at point.
 	 (default-file (dired-get-filename t t))
@@ -458,11 +458,11 @@ into the minibuffer."
   (interactive "P")
   (dired-do-chxxx "Timestamp" dired-touch-program 'touch arg))

-;; Process all the files in FILES in batches of a convenient size,
-;; by means of (FUNCALL FUNCTION ARGS... SOME-FILES...).
-;; Batches are chosen to need less than MAX chars for the file names,
-;; allowing 3 extra characters of separator per file name.
 (defun dired-bunch-files (max function args files)
+"Process all the files in FILES in batches of a convenient size.
+Uses (FUNCALL FUNCTION ARGS... SOME-FILES...). Batches are
+chosen to need less than MAX chars for the file names, allowing 3
+extra characters of separator per file name."
   (let (pending
 	past
 	(pending-length 0)
@@ -594,8 +594,8 @@ with a prefix argument."
 ;;; Subroutines of dired-clean-directory.

 (defun dired-map-dired-file-lines (fun)
-  ;; Perform FUN with point at the end of each non-directory line.
-  ;; FUN takes one argument, the absolute filename.
+"Perform FUN with point at the end of each non-directory line.
+FUN takes one argument, the absolute filename."
   (save-excursion
     (let (file buffer-read-only)
       (goto-char (point-min))
@@ -815,13 +815,14 @@ prompted for the shell command to use interactively."
   "Separates marked files in dired shell commands.")

 (defun dired-shell-stuff-it (command file-list on-each &optional _raw-arg)
-;; "Make up a shell command line from COMMAND and FILE-LIST.
-;; If ON-EACH is t, COMMAND should be applied to each file, else
-;; simply concat all files and apply COMMAND to this.
-;; FILE-LIST's elements will be quoted for the shell."
-;; Might be redefined for smarter things and could then use RAW-ARG
-;; (coming from interactive P and currently ignored) to decide what to do.
-;; Smart would be a way to access basename or extension of file names.
+"Make up a shell command line from COMMAND and FILE-LIST.
+If ON-EACH is t, COMMAND should be applied to each file, else
+simply concat all files and apply COMMAND to this.
+FILE-LIST's elements will be quoted for the shell.
+
+Might be redefined for smarter things and could then use RAW-ARG
+(coming from interactive P and currently ignored) to decide what to do.
+Smart would be a way to access basename or extension of file names."
   (let* ((in-background (string-match "[ \t]*&[ \t]*\\'" command))
 	 (command (if in-background
 		      (substring command 0 (match-beginning 0))
@@ -961,20 +962,21 @@ With a prefix argument, kill that many lines starting with the current line.
 ;;;###autoload
 (defun dired-do-kill-lines (&optional arg fmt)
   "Kill all marked lines (not the files).
-With a prefix argument, kill that many lines starting with the current line.
-\(A negative argument kills backward.)
+With a prefix argument, kill that many lines starting with the
+current line. A negative argument kills backward.

 If you use this command with a prefix argument to kill the line
 for a file that is a directory, which you have inserted in the
 Dired buffer as a subdirectory, then it deletes that subdirectory
 from the buffer as well.

-To kill an entire subdirectory \(without killing its line in the
-parent directory), go to its directory header line and use this
+To kill an entire subdirectory without killing its line in the
+parent directory, go to its directory header line and use this
 command with a prefix argument (the value does not matter).

-To undo the killing, the undo command can be used as normally."
-  ;; Returns count of killed lines.  FMT="" suppresses message.
+To undo the killing, the undo command can be used as normally.
+
+Returns count of killed lines.  FMT=\"\" suppresses message."
   (interactive "P")
   (if arg
       (if (dired-get-subdir)
@@ -1000,8 +1002,8 @@ To undo the killing, the undo command can be used as normally."
 ;;;###begin dired-cp.el

 (defun dired-compress ()
-  ;; Compress or uncompress the current file.
-  ;; Return nil for success, offending filename else.
+"Compress or uncompress the current file.
+Return nil for success, offending filename else."
   (let* (buffer-read-only
 	 (from-file (dired-get-filename))
 	 (new-file (dired-compress-file from-file)))
@@ -1206,11 +1208,11 @@ Return nil if no change in files."
                   (concat file ".Z"))))))))
 \f
 (defun dired-mark-confirm (op-symbol arg)
-  ;; Request confirmation from the user that the operation described
-  ;; by OP-SYMBOL is to be performed on the marked files.
-  ;; Confirmation consists in a y-or-n question with a file list
-  ;; pop-up unless OP-SYMBOL is a member of `dired-no-confirm'.
-  ;; The files used are determined by ARG (as in dired-get-marked-files).
+"Request confirmation from the user for an operation on marked-files.
+The operation is described by OP-SYMBOL. Confirmation consists in
+a y-or-n question with a file list pop-up unless OP-SYMBOL is a
+member of `dired-no-confirm'. The files used are determined by
+ARG (as in dired-get-marked-files)."
   (or (eq dired-no-confirm t)
       (memq op-symbol dired-no-confirm)
       ;; Pass t for DISTINGUISH-ONE-MARKED so that a single file which
@@ -1224,19 +1226,19 @@ Return nil if no change in files."
 				   (dired-mark-prompt arg files) "? ")))))

 (defun dired-map-over-marks-check (fun arg op-symbol &optional show-progress)
-;  "Map FUN over marked files (with second ARG like in dired-map-over-marks)
-; and display failures.
+ "Map FUN over marked files and display failures.
+Second ARG is as in function `dired-map-over-marks'.

-; FUN takes zero args.  It returns non-nil (the offending object, e.g.
-; the short form of the filename) for a failure and probably logs a
-; detailed error explanation using function `dired-log'.
+FUN takes zero args.  It returns non-nil (the offending object, e.g.
+the short form of the filename) for a failure and probably logs a
+detailed error explanation using function `dired-log'.

-; OP-SYMBOL is a symbol describing the operation performed (e.g.
-; `compress').  It is used with `dired-mark-pop-up' to prompt the user
-; (e.g. with `Compress * [2 files]? ') and to display errors (e.g.
-; `Failed to compress 1 of 2 files - type W to see why ("foo")')
+OP-SYMBOL is a symbol describing the operation performed (e.g.
+`compress').  It is used with `dired-mark-pop-up' to prompt the user
+(e.g. with `Compress * [2 files]? ') and to display errors (e.g.
+`Failed to compress 1 of 2 files - type W to see why ("foo")')

-; SHOW-PROGRESS if non-nil means redisplay dired after each file."
+SHOW-PROGRESS if non-nil means redisplay dired after each file."
   (if (dired-mark-confirm op-symbol arg)
       (let* ((total-list;; all of FUN's return values
 	      (dired-map-over-marks (funcall fun) arg show-progress))
@@ -1299,7 +1301,8 @@ uncompress and unpack all the files in the archive."
 ;; Commands for Emacs Lisp files - load and byte compile

 (defun dired-byte-compile ()
-  ;; Return nil for success, offending file name else.
+  "Byte-compile file at POINT.
+Return nil for success; otherwise, the offending file name."
   (let* ((filename (dired-get-filename))
 	 elc-file buffer-read-only failure)
     (condition-case err
@@ -1325,7 +1328,8 @@ uncompress and unpack all the files in the archive."
   (dired-map-over-marks-check #'dired-byte-compile arg 'byte-compile t))

 (defun dired-load ()
-  ;; Return nil for success, offending file name else.
+  "Load file at POINT.
+Return nil for success; otherwise, the offending file name."
   (let ((file (dired-get-filename)) failure)
     (condition-case err
       (load file nil nil t)
@@ -1390,11 +1394,11 @@ See Info node `(emacs)Subdir switches' for more details."
   (revert-buffer))
 \f
 (defun dired-update-file-line (file)
-  ;; Delete the current line, and insert an entry for FILE.
-  ;; If FILE is nil, then just delete the current line.
-  ;; Keeps any marks that may be present in column one (doing this
-  ;; here is faster than with dired-add-entry's optional arg).
-  ;; Does not update other dired buffers.  Use dired-relist-entry for that.
+"Delete the current line, and insert an entry for FILE.
+If FILE is nil, then just delete the current line. Keeps any
+marks that may be present in column one (doing this here is
+faster than with dired-add-entry's optional arg). Does not update
+other dired buffers. Use dired-relist-entry for that."
   (let* ((opoint (line-beginning-position))
          (char (char-after opoint))
          (buffer-read-only))
@@ -1533,10 +1537,9 @@ files matching `dired-omit-regexp'."
     t))

 (defun dired-after-subdir-garbage (dir)
-  ;; Return pos of first file line of DIR, skipping header and total
-  ;; or wildcard lines.
-  ;; Important: never moves into the next subdir.
-  ;; DIR is assumed to be unhidden.
+  "Return pos of first file line of DIR.
+Header lines and total or wildcard lines are skipped. Important:
+never moves into the next subdir. DIR is assumed to be unhidden."
   (save-excursion
     (or (dired-goto-subdir dir) (error "This cannot happen"))
     (forward-line 1)
@@ -1562,8 +1565,8 @@ See `dired-delete-file' in case you wish that."
 			    #'dired-relist-entry file))

 (defun dired-relist-entry (file)
-  ;; Relist the line for FILE, or just add it if it did not exist.
-  ;; FILE must be an absolute file name.
+  "Relist the line for FILE, or just add it if it did not exist.
+FILE must be an absolute file name."
   (let (buffer-read-only marker)
     ;; If cursor is already on FILE's line delete-region will cause
     ;; save-excursion to fail because of floating makers,
@@ -1587,15 +1590,15 @@ Special value `always' suppresses confirmation."
 		 (other :tag "ask" t))
   :group 'dired)

-;; This is a fluid var used in dired-handle-overwrite.  It should be
-;; let-bound whenever dired-copy-file etc are called.  See
-;; dired-create-files for an example.
-(defvar dired-overwrite-confirmed)
+(defvar dired-overwrite-confirmed
+  "A fluid var used in dired-handle-overwrite.
+It should be let-bound whenever dired-copy-file etc are called.
+See `dired-create-files' for an example.")

 (defun dired-handle-overwrite (to)
-  ;; Save old version of file TO that is to be overwritten.
-  ;; `dired-overwrite-confirmed' and `overwrite-backup-query' are fluid vars
-  ;; from dired-create-files.
+"Save old version of file TO that is to be overwritten.
+`dired-overwrite-confirmed' and `overwrite-backup-query' are
+fluid vars from dired-create-files."
   (let (backup)
     (when (and dired-backup-overwrite
 	       dired-overwrite-confirmed
@@ -1712,8 +1715,8 @@ unless OK-IF-ALREADY-EXISTS is non-nil."
       (setq blist (cdr blist)))))

 (defun dired-rename-subdir-1 (dir to)
-  ;; Rename DIR to TO in headerlines and dired-subdir-alist, if DIR or
-  ;; one of its subdirectories is expanded in this buffer.
+"Rename DIR to TO in header lines and dired-subdir-alist, if DIR
+or one of its subdirectories is expanded in this buffer."
   (let ((expanded-dir (expand-file-name dir))
 	(alist dired-subdir-alist)
 	(elt nil))
@@ -1747,10 +1750,10 @@ unless OK-IF-ALREADY-EXISTS is non-nil."
 	  (dired-advertise)))))

 (defun dired-rename-subdir-2 (elt dir to)
-  ;; Update the headerline and dired-subdir-alist element, as well as
-  ;; dired-switches-alist element, of directory described by
-  ;; alist-element ELT to reflect the moving of DIR to TO.  Thus, ELT
-  ;; describes either DIR itself or a subdir of DIR.
+  "Update the headerline and dired-subdir-alist element, as well
+as dired-switches-alist element, of directory described by
+alist-element ELT to reflect the moving of DIR to TO. Thus, ELT
+describes either DIR itself or a subdir of DIR."
   (save-excursion
     (let ((regexp (regexp-quote (directory-file-name dir)))
 	  (newtext (directory-file-name to))
@@ -2007,17 +2010,16 @@ Optional arg HOW-TO determines how to treat the target.
 	 (lambda (_from) target))
        marker-char))))

-;; Read arguments for a marked-files command that wants a file name,
-;; perhaps popping up the list of marked files.
-;; ARG is the prefix arg and indicates whether the files came from
-;; marks (ARG=nil) or a repeat factor (integerp ARG).
-;; If the current file was used, the list has but one element and ARG
-;; does not matter. (It is non-nil, non-integer in that case, namely '(4)).
-;; DEFAULT is the default value to return if the user just hits RET;
-;; if it is omitted or nil, then the name of the directory is used.
-
 (defun dired-mark-read-file-name (prompt dir op-symbol arg files
 					 &optional default)
+  "Read arguments for a marked-files command that wants a file name,
+perhaps popping up the list of marked files. ARG is the prefix
+arg and indicates whether the files came from marks (ARG=nil) or
+a repeat factor (integerp ARG). If the current file was used, the
+list has but one element and ARG does not matter. (It is non-nil,
+non-integer in that case, namely '(4)). DEFAULT is the default
+value to return if the user just hits RET; if it is omitted or
+nil, then the name of the directory is used."
   (dired-mark-pop-up
    nil op-symbol files
    #'read-file-name
@@ -2029,7 +2031,7 @@ Optional arg HOW-TO determines how to treat the target.
     (dired-dwim-target-next)))

 (defun dired-dwim-target-next (&optional all-frames)
-  ;; Return directories from all next windows with dired-mode buffers.
+  "Return directories from all next windows with dired-mode buffers."
   (mapcan (lambda (w)
             (with-current-buffer (window-buffer w)
               (when (eq major-mode 'dired-mode)
@@ -2039,12 +2041,12 @@ Optional arg HOW-TO determines how to treat the target.
                                    'nomini all-frames))))

 (defun dired-dwim-target-next-visible ()
-  ;; Return directories from all next visible windows with dired-mode buffers.
+  "Return directories from all next visible windows with dired-mode buffers."
   (dired-dwim-target-next 'visible))

 (defun dired-dwim-target-recent ()
-  ;; Return directories from all visible windows with dired-mode buffers
-  ;; ordered by most-recently-used.
+  "Return directories from all visible windows with dired-mode
+buffers ordered by most-recently-used."
   (mapcar #'cdr (sort (mapcan (lambda (w)
                                 (with-current-buffer (window-buffer w)
                                   (when (eq major-mode 'dired-mode)
@@ -2055,9 +2057,9 @@ Optional arg HOW-TO determines how to treat the target.
                       (lambda (a b) (> (car a) (car b))))))

 (defun dired-dwim-target-directory ()
-  ;; Try to guess which target directory the user may want.
-  ;; If there is a dired buffer displayed in one of the next windows,
-  ;; use its current subdir, else use current subdir of this dired buffer.
+  "Try to guess which target directory the user may want.
+If there is a dired buffer displayed in one of the next windows,
+use its current subdir, else use current subdir of this dired buffer."
   (let ((this-dir (and (eq major-mode 'dired-mode)
 		       (dired-current-directory))))
     ;; non-dired buffer may want to profit from this function, e.g. vm-uudecode
@@ -2066,16 +2068,16 @@ Optional arg HOW-TO determines how to treat the target.
       this-dir)))

 (defun dired-dwim-target-defaults (fn-list target-dir)
-  ;; Return a list of default values for file-reading functions in Dired.
-  ;; This list may contain directories from Dired buffers in other windows.
-  ;; `fn-list' is a list of file names used to build a list of defaults.
-  ;; When nil or more than one element, a list of defaults will
-  ;; contain only directory names.  `target-dir' is a directory name
-  ;; to exclude from the returned list, for the case when this
-  ;; directory name is already presented in initial input.
-  ;; For Dired operations that support `dired-dwim-target',
-  ;; the argument `target-dir' should have the value returned
-  ;; from `dired-dwim-target-directory'.
+  "Return a list of default values for file-reading functions in Dired.
+This list may contain directories from Dired buffers in other windows.
+`fn-list' is a list of file names used to build a list of defaults.
+When nil or more than one element, a list of defaults will
+contain only directory names.  `target-dir' is a directory name
+to exclude from the returned list, for the case when this
+directory name is already presented in initial input.
+For Dired operations that support `dired-dwim-target',
+the argument `target-dir' should have the value returned
+from `dired-dwim-target-directory'."
   (let ((dired-one-file
 	 (and (consp fn-list) (null (cdr fn-list)) (car fn-list)))
 	(current-dir (and (eq major-mode 'dired-mode)
@@ -2265,14 +2267,14 @@ of `dired-dwim-target', which see."

 (defun dired-do-create-files-regexp
   (file-creator operation arg regexp newname &optional whole-name marker-char)
-  ;; Create a new file for each marked file using regexps.
-  ;; FILE-CREATOR and OPERATION as in dired-create-files.
-  ;; ARG as in dired-get-marked-files.
-  ;; Matches each marked file against REGEXP and constructs the new
-  ;;   filename from NEWNAME (like in function replace-match).
-  ;; Optional arg WHOLE-NAME means match/replace the whole file name
-  ;;   instead of only the non-directory part of the file.
-  ;; Optional arg MARKER-CHAR as in dired-create-files.
+  "Create a new file for each marked file using regexps.
+FILE-CREATOR and OPERATION as in dired-create-files.
+ARG as in dired-get-marked-files.
+Matches each marked file against REGEXP and constructs the new
+  filename from NEWNAME (like in function replace-match).
+Optional arg WHOLE-NAME means match/replace the whole file name
+  instead of only the non-directory part of the file.
+Optional arg MARKER-CHAR as in dired-create-files."
   (let* ((fn-list (dired-get-marked-files nil arg))
 	 (operation-prompt (concat operation " `%s' to `%s'?"))
 	 (rename-regexp-help-form (format-message "\
@@ -2317,8 +2319,8 @@ Type SPC or `y' to %s one match, DEL or `n' to skip to next,
      file-creator operation fn-list regexp-name-constructor marker-char)))

 (defun dired-mark-read-regexp (operation)
-  ;; Prompt user about performing OPERATION.
-  ;; Read and return list of: regexp newname arg whole-name.
+  "Prompt user about performing OPERATION.
+Read and return list of: regexp newname arg whole-name."
   (let* ((whole-name
 	  (equal 0 (prefix-numeric-value current-prefix-arg)))
 	 (arg
@@ -2385,9 +2387,9 @@ See function `dired-do-rename-regexp' for more info."

 (defun dired-create-files-non-directory
   (file-creator basename-constructor operation arg)
-  ;; Perform FILE-CREATOR on the non-directory part of marked files
-  ;; using function BASENAME-CONSTRUCTOR, with query for each file.
-  ;; OPERATION like in dired-create-files, ARG as in dired-get-marked-files.
+  "Perform FILE-CREATOR on the non-directory part of marked files
+using function BASENAME-CONSTRUCTOR, with query for each file.
+OPERATION like in dired-create-files, ARG as in dired-get-marked-files."
   (let (rename-non-directory-query)
     (dired-create-files
      file-creator
@@ -2477,10 +2479,11 @@ If it is already present, overwrite the previous entry;
 With a prefix arg, you may edit the `ls' switches used for this listing.
   You can add `R' to the switches to expand the whole tree starting at
   this subdirectory.
-This function takes some pains to conform to `ls -lR' output."
-  ;; NO-ERROR-IF-NOT-DIR-P needed for special filesystems like
-  ;; Prospero where dired-ls does the right thing, but
-  ;; file-directory-p has not been redefined.
+This function takes some pains to conform to `ls -lR' output.
+
+NO-ERROR-IF-NOT-DIR-P is needed for special filesystems like
+Prospero where dired-ls does the right thing, but
+file-directory-p has not been redefined."
   (interactive
    (list (dired-get-filename)
 	 (if current-prefix-arg
@@ -2526,8 +2529,8 @@ This function takes some pains to conform to `ls -lR' output."
     (restore-buffer-modified-p modflag)))

 (defun dired-insert-subdir-validate (dirname &optional switches)
-  ;; Check that it is valid to insert DIRNAME with SWITCHES.
-  ;; Signal an error if invalid (e.g. user typed `i' on `..').
+  "Check that it is valid to insert DIRNAME with SWITCHES.
+Signal an error if invalid (e.g. user typed `i' on `..')."
   (or (dired-in-this-tree-p dirname (expand-file-name default-directory))
       (error  "%s: not in this directory tree" dirname))
   (let ((real-switches (or switches dired-subdir-switches)))
@@ -2543,12 +2546,12 @@ This function takes some pains to conform to `ls -lR' output."
 	 '("F" "b"))))))

 (defun dired-alist-add (dir new-marker)
-  ;; Add new DIR at NEW-MARKER.  Sort alist.
+  "Add new DIR at NEW-MARKER.  Sort alist."
   (dired-alist-add-1 dir new-marker)
   (dired-alist-sort))

 (defun dired-alist-sort ()
-  ;; Keep the alist sorted on buffer position.
+  "Keep the alist sorted on buffer position."
   (setq dired-subdir-alist
 	(sort dired-subdir-alist
 	      (lambda (elt1 elt2)
@@ -2575,7 +2578,7 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
     m-alist))

 (defun dired-insert-subdir-newpos (new-dir)
-  ;; Find pos for new subdir, according to tree order.
+  "Find pos for new subdir, according to tree order."
   ;;(goto-char (point-max))
   (let ((alist dired-subdir-alist) elt dir new-pos)
     (while alist
@@ -2594,8 +2597,8 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
   (point))

 (defun dired-insert-subdir-del (element)
-  ;; Erase an already present subdir (given by ELEMENT) from buffer.
-  ;; Move to that buffer position.  Return a mark-alist.
+  "Erase an already present subdir (given by ELEMENT) from buffer.
+Move to that buffer position.  Return a mark-alist."
   (let ((begin-marker (cdr element)))
     (goto-char begin-marker)
     ;; Are at beginning of subdir (and inside it!).  Now determine its end:
@@ -2607,8 +2610,8 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
       (delete-region begin-marker (point)))))

 (defun dired-insert-subdir-doinsert (dirname switches)
-  ;; Insert ls output after point.
-  ;; Return the boundary of the inserted text (as list of BEG and END).
+  "Insert ls output after point.
+Return the boundary of the inserted text (as list of BEG and END)."
   (save-excursion
     (let ((begin (point)))
       (let ((dired-actual-switches
@@ -2643,14 +2646,15 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
 	    (run-hooks 'dired-after-readin-hook))))))

 (defun dired-tree-lessp (dir1 dir2)
-  ;; Lexicographic order on file name components, like `ls -lR':
-  ;; DIR1 < DIR2 if DIR1 comes *before* DIR2 in an `ls -lR' listing,
-  ;;   i.e., if DIR1 is a (grand)parent dir of DIR2,
-  ;;   or DIR1 and DIR2 are in the same parentdir and their last
-  ;;   components are string-lessp.
-  ;; Thus ("/usr/" "/usr/bin") and ("/usr/a/" "/usr/b/") are tree-lessp.
-  ;; string-lessp could arguably be replaced by file-newer-than-file-p
-  ;;   if dired-actual-switches contained t.
+  "Lexicographic order on file name components, like `ls -lR':
+DIR1 < DIR2 if DIR1 comes *before* DIR2 in an `ls -lR' listing,
+i.e., if DIR1 is a (grand)parent dir of DIR2, or DIR1 and DIR2
+are in the same parentdir and their last components are
+string-lessp.
+
+Thus (\"/usr/\" \"/usr/bin\") and (\"/usr/a/\" \"/usr/b/\") are
+tree-lessp. `string-lessp' could arguably be replaced by
+`file-newer-than-file-p' if dired-actual-switches contained t."
   (setq dir1 (file-name-as-directory dir1)
 	dir2 (file-name-as-directory dir2))
   (let ((components-1 (dired-split "/" dir1))

bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED]

[Eli Zaretskii]

> Date: Sun, 25 Apr 2021 01:22:12 -0400
> From: Boruch Baum <boruch_baum@gmx.com>
> Cc: "47957@debbugs.gnu.org" <47957@debbugs.gnu.org>
> 
> Done. Updated patch attached.

Thanks.  This still needs some work to make it compatible with our
conventions.  First, some general issues will almost all of the doc
strings in the patch:

  . The first line of a doc string should be a complete sentence
    mentioning the mandatory arguments.
  . Two spaces between sentences, per US English conventions.
  . An opening parenthesis or grave accent in column zero should be
    escaped by a backslash.

A few specific comments:

>  (defun dired-map-dired-file-lines (fun)
> -  ;; Perform FUN with point at the end of each non-directory line.
> -  ;; FUN takes one argument, the absolute filename.
> +"Perform FUN with point at the end of each non-directory line.

"Perform FUN" sounds awkward.  I suggest "Call FUN" instead.

>  (defun dired-compress ()
> -  ;; Compress or uncompress the current file.
> -  ;; Return nil for success, offending filename else.

This and other uses of "offending" are not really a good idea.  We are
not talking about files that cause some trouble.  Suggest to find a
better word.

> -;; Read arguments for a marked-files command that wants a file name,
> -;; perhaps popping up the list of marked files.
> -;; ARG is the prefix arg and indicates whether the files came from
> -;; marks (ARG=nil) or a repeat factor (integerp ARG).
> -;; If the current file was used, the list has but one element and ARG
> -;; does not matter. (It is non-nil, non-integer in that case, namely '(4)).
> -;; DEFAULT is the default value to return if the user just hits RET;
> -;; if it is omitted or nil, then the name of the directory is used.
> -
>  (defun dired-mark-read-file-name (prompt dir op-symbol arg files
>  					 &optional default)
> +  "Read arguments for a marked-files command that wants a file name,
> +perhaps popping up the list of marked files. ARG is the prefix
> +arg and indicates whether the files came from marks (ARG=nil) or
> +a repeat factor (integerp ARG). If the current file was used, the
> +list has but one element and ARG does not matter. (It is non-nil,
> +non-integer in that case, namely '(4)). DEFAULT is the default
> +value to return if the user just hits RET; if it is omitted or
> +nil, then the name of the directory is used."

Some of the comments that you converted to doc strings are
descriptions of the implementation.  the above is one example.  I'm
not sure it is a good idea to have doc strings which do that, because
understanding how to use this function in Lisp programs is not easy
given such low-level details and nothing else.  Maybe just leave them
as comments?

> +  "Return a list of default values for file-reading functions in Dired.
> +This list may contain directories from Dired buffers in other windows.
> +`fn-list' is a list of file names used to build a list of defaults.
> +When nil or more than one element, a list of defaults will
> +contain only directory names.  `target-dir' is a directory name

This uses non-standard way of naming the function's arguments: they
should be up-cased and not quoted.

> +FILE-CREATOR and OPERATION as in dired-create-files.
> +ARG as in dired-get-marked-files.

These two sentences lack the verb ("are", I guess).

>  (defun dired-alist-sort ()
> -  ;; Keep the alist sorted on buffer position.
> +  "Keep the alist sorted on buffer position."

This references some alist without naming it.

>  (defun dired-insert-subdir-newpos (new-dir)
> -  ;; Find pos for new subdir, according to tree order.
> +  "Find pos for new subdir, according to tree order."

This doesn't mention the function's argument.

bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED]

[Boruch Baum]

On 2021-04-25 11:15, Eli Zaretskii wrote:
> > Date: Sun, 25 Apr 2021 01:22:12 -0400
> > From: Boruch Baum <boruch_baum@gmx.com>
> > Cc: "47957@debbugs.gnu.org" <47957@debbugs.gnu.org>
> >
> > Done. Updated patch attached.
>
> Thanks.  This still needs some work to make it compatible with our
> conventions.

All your feedback is well-taken, but I'm moving on to other things with
the patch as submitted. If as an improvement over the existing file the
patch isn't good enough to be committed for someone to continue with,
so be it.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

bug#47957: dired-aux.el: convert comments to doctrings

[Lars Ingebrigtsen]

Boruch Baum <boruch_baum@gmx.com> writes:

> All your feedback is well-taken, but I'm moving on to other things with
> the patch as submitted. If as an improvement over the existing file the
> patch isn't good enough to be committed for someone to continue with,
> so be it.

Looking over the changes -- some look good to me, and some don't.
Converting comments to doc strings isn't a mechanical process --
comments should describe what a function does, while internal details
should be left as comments.

So I'm closing this bug report without applying the patch, because in
total I think it's a change for the negative.

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

bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED]

[Drew Adams]

> > Thanks for doing this.
> 
> Quite welcome. Let's see what it takes to get merged...
> 
> > A minor suggestion (for consideration) for `dired-do-kill-lines'
> > ...
> > Say "remove", not "kill" (which generally has to do with removing
> > ...
> > (Also, don't forget to prefix lines that start with ( with \.)
> 
> Done. Updated patch attached.

Some feedback, for consideration.  I see now, after writing
all this, that Eli also provided feedback.  HTH, anyway.

1.
+Operates on marked files and refresh their file lines.
                              refreshes

Start each <ARG NAME> is... on its own line, including
OP-SYMBOL and ARG.

2.
+"Process all the files in FILES...

  Process FILES...

+Uses (FUNCALL FUNCTION ARGS... SOME-FILES...).

 Applies FUNCTION to ARGS and SOME-FILES, where SOME-FILES
 is a batch of at most MAX files.

(The comment in the code was wrong.)

3.
+"Make up a shell command line from 

  Return a shell command line derived from

+If ON-EACH is t, COMMAND should be applied to each file, else
+simply concat all files and apply COMMAND to this.
+FILE-LIST's elements will be quoted for the shell.

 By default, apply COMMAND to all files together.
 Non-nil ON-EACH means apply COMMAND to each file instead.

 Quote the files in FILE-LIST for the shell.

+Might be redefined for smarter things and could then use RAW-ARG
+(coming from interactive P and currently ignored) to decide what to do.
+Smart would be a way to access basename or extension of file names."

Remove that - I think it should just remain a code comment.

4.
You indicate that you applied my suggestion to speak of
removing, rather than killing, lines.  But I don't see
that you did that, at all.

5.
+"Compress or uncompress the current file.
+Return nil for success, offending filename else."

  Compress or uncompress the file named on the current line.
  Return nil for success or the file name for failure.

6.
+"Request confirmation from the user for an operation on marked-files.
+The operation is described by OP-SYMBOL. Confirmation consists in
+a y-or-n question with a file list pop-up unless OP-SYMBOL is a
+member of `dired-no-confirm'.

  Request confirmation from user for an operation on the marked files.
  OP-SYMBOL is a symbol describing the operation performed (e.g.
  `compress').

  If `dired-no-confirm' is t or OP-SYMBOL is a member of list
  `dired-no-confirm' then this is a no-op: no confirmation is needed.
  Otherwise, confirmation is requested with `y-or-n-p'.

7.
FWIW: For `dired-map-over-marks-check' I use this (adapted
by removing mention of added &rest arg FUN-ARGS and function
`diredp-map-over-marks-and-report'):

Map FUN over marked lines and report failures.
FUN should return nil for success and non-nil (the offending object,
e.g. the short form of the filename) for a failure.  FUN can log a
detailed error explanation using `dired-log'.

MARK-ARG is as the second argument of `dired-map-over-marks'.

OP-SYMBOL is a symbol describing the operation performed (e.g.
`compress').  It is used with `dired-mark-pop-up' to prompt the user
\(e.g. with `Compress * [2 files]? ') and to display errors (e.g.
`Failed to compress 1 of 2 files - type ? for details (\"foo\")')

SHOW-PROGRESS if non-nil means redisplay Dired after each file.

FUN-ARGS is the list of any remaining args to
`dired-map-over-marks-check'.  Function FUN is applied to these
arguments.

8.
+  "Byte-compile file at POINT.

and

+  "Load file at POINT.

POINT shouldn't be uppercase.  And it shouldn't be mentioned.
The cursor need not be on the file name.

Use something like this instead:

   Byte-compile the file named on the current line.

9.
+If FILE is nil, then just delete the current line. Keeps any
+marks that may be present in column one (doing this here is
+faster than with dired-add-entry's optional arg). Does not update
+other dired buffers. Use dired-relist-entry for that."

 If FILE is nil, then just delete the current line.
 Keep any mark in column one.

 This does not update other dired buffers.
 \(Use `dired-relist-entry' for that.)

10.
+  "Return pos of first file line of DIR.
    Return the position of the first file line of DIR.
    DIR is assumed to be visible, not hidden.

+Header lines and total or wildcard lines are skipped. Important:
+never moves into the next subdir. DIR is assumed to be unhidden."

    This never moves into the next subdir listing.

(No need to say what's skipped, as it says "first file line".)

11.
+  "A fluid var used in dired-handle-overwrite.
+It should be let-bound whenever dired-copy-file etc are called.
+See `dired-create-files' for an example.")

I don't know what this is - it was apparently added after Emacs 27.
But the first line should not say what it says.  The first line
should say what the variable does, is, or represents.  Presumably
its value controls or defines how overwriting is handled.

This doc string is not good, IMO.  Maybe the variable itself
is ill-advised; dunno.  Maybe that info is helpful as a code
comment; dunno.

12.
What happened to a doc string for `dired-rename-subdir'?  That's
more important than doc strings for `*-1' and `*-2'.  The latter
doc strings should say these are helper functions for the main fn.

13.
+"Rename DIR to TO in header lines and dired-subdir-alist, if DIR
+or one of its subdirectories is expanded in this buffer."

The args should have the same names as in `dired-rename-subdir'
(so a code change also).

  Helper for `dired-rename-subdir'.
  Rename only if FROM-DIR or one of its subdirectories is...

(Requires study of the code.  Sorry, no time.)

14.
+  "Update the headerline and dired-subdir-alist element, as well
+as dired-switches-alist element, of directory described by
+alist-element ELT to reflect the moving of DIR to TO. Thus, ELT
+describes either DIR itself or a subdir of DIR."

Start with "Helper for `dired-rename-subdir-1'."

headerline -> header line

   ELT is an element of `dired-subdir-alist'.  It describes
   either FROM-DIR or one of its subdirectories.

15.
+  "Read arguments for a marked-files command that wants a file name,
+perhaps popping up the list of marked files. ARG is the prefix
+arg and indicates whether the files came from marks (ARG=nil) or
+a repeat factor (integerp ARG). If the current file was used, the
+list has but one element and ARG does not matter. (It is non-nil,
+non-integer in that case, namely '(4)). DEFAULT is the default
+value to return if the user just hits RET; if it is omitted or
+nil, then the name of the directory is used."

    Use `dired-mark-pop-up' to read a file name.
    PROMPT, ARG, and FILES are used for prompting.
     PROMPT is a `format' string that is applied to the result of applying
     `dired-mark-prompt' to ARG and FILES.
    OP-SYMBOL, FILES, DIR, and DEFAULT are passed to `dired-mark-pop-up'.

16.
+  "Return directories from all next visible windows with dired-mode buffers."
    Return a list of directories from visible `next-window' Dired buffers.
    
17.
+  "Return directories from all visible windows with dired-mode
+buffers ordered by most-recently-used."

    Return a list of directories from visible recent Dired buffers.

18.
+  "Try to guess which target directory the user may want.
+If there is a dired buffer displayed in one of the next windows,
+use its current subdir, else use current subdir of this dired buffer."

    Return a directory the user might want as a target.
    Prefer the current subdir of a Dired `next-window' buffer.
    If none, return the current subdir of this buffer.

19.
+  "Return a list of default values for file-reading functions in Dired.
+This list may contain directories from Dired buffers in other windows.
+`fn-list' is a list of file names used to build a list of defaults.
+When nil or more than one element, a list of defaults will
+contain only directory names.  `target-dir' is a directory name
+to exclude from the returned list, for the case when this
+directory name is already presented in initial input.
+For Dired operations that support `dired-dwim-target',
+the argument `target-dir' should have the value returned
+from `dired-dwim-target-directory'."

Change arg FN-LIST to FILES.  Then it can be used in the doc
with no other description.

   Return a list of default values for file-reading functions.
   This can include directories from Dired buffers in other windows.

   If FILES is a singleton list (FILE) then the return value can
    include this or other directories with FILE appended, as well
    as just other directories.
   If FILES is not a singleton list then the return value includes
    only directories.

Sorry, but I've run out of time to spend on this.  For #19,
TARGET-DIR needs to be described properly.  The comment doesn't
do that, AFAICT.

HTH.  Can't spend more time on this.  Hopefully someone else can
take a look.  It's not enough to move the comments to doc strings,
I think.

bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED]

[Boruch Baum]

[-- Attachment #1: Type: text/plain, Size: 765 bytes --]

On 2021-04-25 18:21, Drew Adams wrote:
> You indicate that you applied my suggestion to speak of
> removing, rather than killing, lines.  But I don't see
> that you did that, at all.

Oops. Sent the wrong diff, I guess. Sorry. Here it is now.

> Sorry, but I've run out of time to spend on this.

Me too. At least for now.

> HTH.  Can't spend more time on this.  Hopefully someone else can
> take a look.  It's not enough to move the comments to doc strings,
> I think.

It was an easy lift to offer a big improvement, but agreed, not perfect.
My opinion is that until the work can be continued, it's desirable over
the prior state, but that's not for me to decide.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

[-- Attachment #2: dired-aux-3.patch --]
[-- Type: text/x-diff, Size: 26430 bytes --]

diff --git a/dired-aux.el b/dired-aux.el
index 3ee877e..1c10990 100644
--- a/dired-aux.el
+++ b/dired-aux.el
@@ -314,12 +314,12 @@ List has a form of (file-name full-file-name (attribute-list))."
 ;;; Change file attributes

 (defun dired-do-chxxx (attribute-name program op-symbol arg)
-  ;; Change file attributes (group, owner, timestamp) of marked files and
-  ;; refresh their file lines.
-  ;; ATTRIBUTE-NAME is a string describing the attribute to the user.
-  ;; PROGRAM is the program used to change the attribute.
-  ;; OP-SYMBOL is the type of operation (for use in `dired-mark-pop-up').
-  ;; ARG describes which files to use, as in `dired-get-marked-files'.
+  "Change file attributes (group, owner, timestamp).
+Operates on marked files and refresh their file lines.
+ATTRIBUTE-NAME is a string describing the attribute to the user.
+PROGRAM is the program used to change the attribute. OP-SYMBOL is
+the type of operation (for use in `dired-mark-pop-up'). ARG
+describes which files to use, as in `dired-get-marked-files'."
   (let* ((files (dired-get-marked-files t arg nil nil t))
 	 ;; The source of default file attributes is the file at point.
 	 (default-file (dired-get-filename t t))
@@ -458,11 +458,11 @@ into the minibuffer."
   (interactive "P")
   (dired-do-chxxx "Timestamp" dired-touch-program 'touch arg))

-;; Process all the files in FILES in batches of a convenient size,
-;; by means of (FUNCALL FUNCTION ARGS... SOME-FILES...).
-;; Batches are chosen to need less than MAX chars for the file names,
-;; allowing 3 extra characters of separator per file name.
 (defun dired-bunch-files (max function args files)
+"Process all the files in FILES in batches of a convenient size.
+Uses (FUNCALL FUNCTION ARGS... SOME-FILES...). Batches are
+chosen to need less than MAX chars for the file names, allowing 3
+extra characters of separator per file name."
   (let (pending
 	past
 	(pending-length 0)
@@ -594,8 +594,8 @@ with a prefix argument."
 ;;; Subroutines of dired-clean-directory.

 (defun dired-map-dired-file-lines (fun)
-  ;; Perform FUN with point at the end of each non-directory line.
-  ;; FUN takes one argument, the absolute filename.
+"Perform FUN with point at the end of each non-directory line.
+FUN takes one argument, the absolute filename."
   (save-excursion
     (let (file buffer-read-only)
       (goto-char (point-min))
@@ -793,7 +793,8 @@ prompted for the shell command to use interactively."
 	           ((need-confirm-p command "?")
 	            (y-or-n-p (format-message
 			       "Confirm--do you mean to use `?' as a wildcard? ")))
-	           (t))))
+	           (t)))
+         (win (selected-window)))
     (cond ((not ok) (message "Command canceled"))
           (t
            (if on-each
@@ -804,7 +805,8 @@ prompted for the shell command to use interactively."
 	                          nil file-list)
 	     ;; execute the shell command
 	     (dired-run-shell-command
-	      (dired-shell-stuff-it command file-list nil arg))))))))
+	      (dired-shell-stuff-it command file-list nil arg)))))
+    (select-window win))))

 ;; Might use {,} for bash or csh:
 (defvar dired-mark-prefix ""
@@ -815,13 +817,14 @@ prompted for the shell command to use interactively."
   "Separates marked files in dired shell commands.")

 (defun dired-shell-stuff-it (command file-list on-each &optional _raw-arg)
-;; "Make up a shell command line from COMMAND and FILE-LIST.
-;; If ON-EACH is t, COMMAND should be applied to each file, else
-;; simply concat all files and apply COMMAND to this.
-;; FILE-LIST's elements will be quoted for the shell."
-;; Might be redefined for smarter things and could then use RAW-ARG
-;; (coming from interactive P and currently ignored) to decide what to do.
-;; Smart would be a way to access basename or extension of file names.
+"Make up a shell command line from COMMAND and FILE-LIST.
+If ON-EACH is t, COMMAND should be applied to each file, else
+simply concat all files and apply COMMAND to this.
+FILE-LIST's elements will be quoted for the shell.
+
+Might be redefined for smarter things and could then use RAW-ARG
+\(coming from interactive P and currently ignored) to decide what to do.
+Smart would be a way to access basename or extension of file names."
   (let* ((in-background (string-match "[ \t]*&[ \t]*\\'" command))
 	 (command (if in-background
 		      (substring command 0 (match-beginning 0))
@@ -960,21 +963,23 @@ With a prefix argument, kill that many lines starting with the current line.

 ;;;###autoload
 (defun dired-do-kill-lines (&optional arg fmt)
-  "Kill all marked lines (not the files).
-With a prefix argument, kill that many lines starting with the current line.
-\(A negative argument kills backward.)
+  "Remove all marked lines (not the files).
+With a prefix argument, remove that many lines starting with the
+current line. A negative argument removes backward.

-If you use this command with a prefix argument to kill the line
+If you use this command with a prefix argument to remove the line
 for a file that is a directory, which you have inserted in the
-Dired buffer as a subdirectory, then it deletes that subdirectory
-from the buffer as well.
+Dired buffer as a subdirectory, then it removes the lines of that
+subdirectory from the buffer as well.
+
+To remove the lines of an entire subdirectory without removing
+its line in the parent directory, go to its directory header line
+and use this command with a prefix argument (the value does not
+matter).

-To kill an entire subdirectory \(without killing its line in the
-parent directory), go to its directory header line and use this
-command with a prefix argument (the value does not matter).
+To undo the removal, the undo command can be used as normally.

-To undo the killing, the undo command can be used as normally."
-  ;; Returns count of killed lines.  FMT="" suppresses message.
+Returns count of removed lines.  FMT=\"\" suppresses message."
   (interactive "P")
   (if arg
       (if (dired-get-subdir)
@@ -1000,8 +1005,8 @@ To undo the killing, the undo command can be used as normally."
 ;;;###begin dired-cp.el

 (defun dired-compress ()
-  ;; Compress or uncompress the current file.
-  ;; Return nil for success, offending filename else.
+"Compress or uncompress the current file.
+Return nil for success, offending filename else."
   (let* (buffer-read-only
 	 (from-file (dired-get-filename))
 	 (new-file (dired-compress-file from-file)))
@@ -1206,11 +1211,11 @@ Return nil if no change in files."
                   (concat file ".Z"))))))))
 \f
 (defun dired-mark-confirm (op-symbol arg)
-  ;; Request confirmation from the user that the operation described
-  ;; by OP-SYMBOL is to be performed on the marked files.
-  ;; Confirmation consists in a y-or-n question with a file list
-  ;; pop-up unless OP-SYMBOL is a member of `dired-no-confirm'.
-  ;; The files used are determined by ARG (as in dired-get-marked-files).
+"Request confirmation from the user for an operation on marked-files.
+The operation is described by OP-SYMBOL. Confirmation consists in
+a y-or-n question with a file list pop-up unless OP-SYMBOL is a
+member of `dired-no-confirm'. The files used are determined by
+ARG (as in dired-get-marked-files)."
   (or (eq dired-no-confirm t)
       (memq op-symbol dired-no-confirm)
       ;; Pass t for DISTINGUISH-ONE-MARKED so that a single file which
@@ -1224,19 +1229,19 @@ Return nil if no change in files."
 				   (dired-mark-prompt arg files) "? ")))))

 (defun dired-map-over-marks-check (fun arg op-symbol &optional show-progress)
-;  "Map FUN over marked files (with second ARG like in dired-map-over-marks)
-; and display failures.
+ "Map FUN over marked files and display failures.
+Second ARG is as in function `dired-map-over-marks'.

-; FUN takes zero args.  It returns non-nil (the offending object, e.g.
-; the short form of the filename) for a failure and probably logs a
-; detailed error explanation using function `dired-log'.
+FUN takes zero args.  It returns non-nil (the offending object, e.g.
+the short form of the filename) for a failure and probably logs a
+detailed error explanation using function `dired-log'.

-; OP-SYMBOL is a symbol describing the operation performed (e.g.
-; `compress').  It is used with `dired-mark-pop-up' to prompt the user
-; (e.g. with `Compress * [2 files]? ') and to display errors (e.g.
-; `Failed to compress 1 of 2 files - type W to see why ("foo")')
+OP-SYMBOL is a symbol describing the operation performed (e.g.
+`compress').  It is used with `dired-mark-pop-up' to prompt the user
+\(e.g. with `Compress * [2 files]? ') and to display errors (e.g.
+`Failed to compress 1 of 2 files - type W to see why ("foo")')

-; SHOW-PROGRESS if non-nil means redisplay dired after each file."
+SHOW-PROGRESS if non-nil means redisplay dired after each file."
   (if (dired-mark-confirm op-symbol arg)
       (let* ((total-list;; all of FUN's return values
 	      (dired-map-over-marks (funcall fun) arg show-progress))
@@ -1299,7 +1304,8 @@ uncompress and unpack all the files in the archive."
 ;; Commands for Emacs Lisp files - load and byte compile

 (defun dired-byte-compile ()
-  ;; Return nil for success, offending file name else.
+  "Byte-compile file at POINT.
+Return nil for success; otherwise, the offending file name."
   (let* ((filename (dired-get-filename))
 	 elc-file buffer-read-only failure)
     (condition-case err
@@ -1325,7 +1331,8 @@ uncompress and unpack all the files in the archive."
   (dired-map-over-marks-check #'dired-byte-compile arg 'byte-compile t))

 (defun dired-load ()
-  ;; Return nil for success, offending file name else.
+  "Load file at POINT.
+Return nil for success; otherwise, the offending file name."
   (let ((file (dired-get-filename)) failure)
     (condition-case err
       (load file nil nil t)
@@ -1390,11 +1397,11 @@ See Info node `(emacs)Subdir switches' for more details."
   (revert-buffer))
 \f
 (defun dired-update-file-line (file)
-  ;; Delete the current line, and insert an entry for FILE.
-  ;; If FILE is nil, then just delete the current line.
-  ;; Keeps any marks that may be present in column one (doing this
-  ;; here is faster than with dired-add-entry's optional arg).
-  ;; Does not update other dired buffers.  Use dired-relist-entry for that.
+"Delete the current line, and insert an entry for FILE.
+If FILE is nil, then just delete the current line. Keeps any
+marks that may be present in column one (doing this here is
+faster than with dired-add-entry's optional arg). Does not update
+other dired buffers. Use dired-relist-entry for that."
   (let* ((opoint (line-beginning-position))
          (char (char-after opoint))
          (buffer-read-only))
@@ -1533,10 +1540,9 @@ files matching `dired-omit-regexp'."
     t))

 (defun dired-after-subdir-garbage (dir)
-  ;; Return pos of first file line of DIR, skipping header and total
-  ;; or wildcard lines.
-  ;; Important: never moves into the next subdir.
-  ;; DIR is assumed to be unhidden.
+  "Return pos of first file line of DIR.
+Header lines and total or wildcard lines are skipped. Important:
+never moves into the next subdir. DIR is assumed to be unhidden."
   (save-excursion
     (or (dired-goto-subdir dir) (error "This cannot happen"))
     (forward-line 1)
@@ -1562,8 +1568,8 @@ See `dired-delete-file' in case you wish that."
 			    #'dired-relist-entry file))

 (defun dired-relist-entry (file)
-  ;; Relist the line for FILE, or just add it if it did not exist.
-  ;; FILE must be an absolute file name.
+  "Relist the line for FILE, or just add it if it did not exist.
+FILE must be an absolute file name."
   (let (buffer-read-only marker)
     ;; If cursor is already on FILE's line delete-region will cause
     ;; save-excursion to fail because of floating makers,
@@ -1587,15 +1593,15 @@ Special value `always' suppresses confirmation."
 		 (other :tag "ask" t))
   :group 'dired)

-;; This is a fluid var used in dired-handle-overwrite.  It should be
-;; let-bound whenever dired-copy-file etc are called.  See
-;; dired-create-files for an example.
-(defvar dired-overwrite-confirmed)
+(defvar dired-overwrite-confirmed
+  "A fluid var used in dired-handle-overwrite.
+It should be let-bound whenever dired-copy-file etc are called.
+See `dired-create-files' for an example.")

 (defun dired-handle-overwrite (to)
-  ;; Save old version of file TO that is to be overwritten.
-  ;; `dired-overwrite-confirmed' and `overwrite-backup-query' are fluid vars
-  ;; from dired-create-files.
+"Save old version of file TO that is to be overwritten.
+`dired-overwrite-confirmed' and `overwrite-backup-query' are
+fluid vars from dired-create-files."
   (let (backup)
     (when (and dired-backup-overwrite
 	       dired-overwrite-confirmed
@@ -1712,8 +1718,8 @@ unless OK-IF-ALREADY-EXISTS is non-nil."
       (setq blist (cdr blist)))))

 (defun dired-rename-subdir-1 (dir to)
-  ;; Rename DIR to TO in headerlines and dired-subdir-alist, if DIR or
-  ;; one of its subdirectories is expanded in this buffer.
+"Rename DIR to TO in header lines and dired-subdir-alist, if DIR
+or one of its subdirectories is expanded in this buffer."
   (let ((expanded-dir (expand-file-name dir))
 	(alist dired-subdir-alist)
 	(elt nil))
@@ -1747,10 +1753,10 @@ unless OK-IF-ALREADY-EXISTS is non-nil."
 	  (dired-advertise)))))

 (defun dired-rename-subdir-2 (elt dir to)
-  ;; Update the headerline and dired-subdir-alist element, as well as
-  ;; dired-switches-alist element, of directory described by
-  ;; alist-element ELT to reflect the moving of DIR to TO.  Thus, ELT
-  ;; describes either DIR itself or a subdir of DIR.
+  "Update the headerline and dired-subdir-alist element, as well
+as dired-switches-alist element, of directory described by
+alist-element ELT to reflect the moving of DIR to TO. Thus, ELT
+describes either DIR itself or a subdir of DIR."
   (save-excursion
     (let ((regexp (regexp-quote (directory-file-name dir)))
 	  (newtext (directory-file-name to))
@@ -2007,17 +2013,16 @@ Optional arg HOW-TO determines how to treat the target.
 	 (lambda (_from) target))
        marker-char))))

-;; Read arguments for a marked-files command that wants a file name,
-;; perhaps popping up the list of marked files.
-;; ARG is the prefix arg and indicates whether the files came from
-;; marks (ARG=nil) or a repeat factor (integerp ARG).
-;; If the current file was used, the list has but one element and ARG
-;; does not matter. (It is non-nil, non-integer in that case, namely '(4)).
-;; DEFAULT is the default value to return if the user just hits RET;
-;; if it is omitted or nil, then the name of the directory is used.
-
 (defun dired-mark-read-file-name (prompt dir op-symbol arg files
 					 &optional default)
+  "Read arguments for a marked-files command that wants a file name,
+perhaps popping up the list of marked files. ARG is the prefix
+arg and indicates whether the files came from marks (ARG=nil) or
+a repeat factor (integerp ARG). If the current file was used, the
+list has but one element and ARG does not matter. (It is non-nil,
+non-integer in that case, namely '(4)). DEFAULT is the default
+value to return if the user just hits RET; if it is omitted or
+nil, then the name of the directory is used."
   (dired-mark-pop-up
    nil op-symbol files
    #'read-file-name
@@ -2029,7 +2034,7 @@ Optional arg HOW-TO determines how to treat the target.
     (dired-dwim-target-next)))

 (defun dired-dwim-target-next (&optional all-frames)
-  ;; Return directories from all next windows with dired-mode buffers.
+  "Return directories from all next windows with dired-mode buffers."
   (mapcan (lambda (w)
             (with-current-buffer (window-buffer w)
               (when (eq major-mode 'dired-mode)
@@ -2039,12 +2044,12 @@ Optional arg HOW-TO determines how to treat the target.
                                    'nomini all-frames))))

 (defun dired-dwim-target-next-visible ()
-  ;; Return directories from all next visible windows with dired-mode buffers.
+  "Return directories from all next visible windows with dired-mode buffers."
   (dired-dwim-target-next 'visible))

 (defun dired-dwim-target-recent ()
-  ;; Return directories from all visible windows with dired-mode buffers
-  ;; ordered by most-recently-used.
+  "Return directories from all visible windows with dired-mode
+buffers ordered by most-recently-used."
   (mapcar #'cdr (sort (mapcan (lambda (w)
                                 (with-current-buffer (window-buffer w)
                                   (when (eq major-mode 'dired-mode)
@@ -2055,9 +2060,9 @@ Optional arg HOW-TO determines how to treat the target.
                       (lambda (a b) (> (car a) (car b))))))

 (defun dired-dwim-target-directory ()
-  ;; Try to guess which target directory the user may want.
-  ;; If there is a dired buffer displayed in one of the next windows,
-  ;; use its current subdir, else use current subdir of this dired buffer.
+  "Try to guess which target directory the user may want.
+If there is a dired buffer displayed in one of the next windows,
+use its current subdir, else use current subdir of this dired buffer."
   (let ((this-dir (and (eq major-mode 'dired-mode)
 		       (dired-current-directory))))
     ;; non-dired buffer may want to profit from this function, e.g. vm-uudecode
@@ -2066,16 +2071,16 @@ Optional arg HOW-TO determines how to treat the target.
       this-dir)))

 (defun dired-dwim-target-defaults (fn-list target-dir)
-  ;; Return a list of default values for file-reading functions in Dired.
-  ;; This list may contain directories from Dired buffers in other windows.
-  ;; `fn-list' is a list of file names used to build a list of defaults.
-  ;; When nil or more than one element, a list of defaults will
-  ;; contain only directory names.  `target-dir' is a directory name
-  ;; to exclude from the returned list, for the case when this
-  ;; directory name is already presented in initial input.
-  ;; For Dired operations that support `dired-dwim-target',
-  ;; the argument `target-dir' should have the value returned
-  ;; from `dired-dwim-target-directory'.
+  "Return a list of default values for file-reading functions in Dired.
+This list may contain directories from Dired buffers in other windows.
+`fn-list' is a list of file names used to build a list of defaults.
+When nil or more than one element, a list of defaults will
+contain only directory names.  `target-dir' is a directory name
+to exclude from the returned list, for the case when this
+directory name is already presented in initial input.
+For Dired operations that support `dired-dwim-target',
+the argument `target-dir' should have the value returned
+from `dired-dwim-target-directory'."
   (let ((dired-one-file
 	 (and (consp fn-list) (null (cdr fn-list)) (car fn-list)))
 	(current-dir (and (eq major-mode 'dired-mode)
@@ -2265,14 +2270,14 @@ of `dired-dwim-target', which see."

 (defun dired-do-create-files-regexp
   (file-creator operation arg regexp newname &optional whole-name marker-char)
-  ;; Create a new file for each marked file using regexps.
-  ;; FILE-CREATOR and OPERATION as in dired-create-files.
-  ;; ARG as in dired-get-marked-files.
-  ;; Matches each marked file against REGEXP and constructs the new
-  ;;   filename from NEWNAME (like in function replace-match).
-  ;; Optional arg WHOLE-NAME means match/replace the whole file name
-  ;;   instead of only the non-directory part of the file.
-  ;; Optional arg MARKER-CHAR as in dired-create-files.
+  "Create a new file for each marked file using regexps.
+FILE-CREATOR and OPERATION as in dired-create-files.
+ARG as in dired-get-marked-files.
+Matches each marked file against REGEXP and constructs the new
+  filename from NEWNAME (like in function replace-match).
+Optional arg WHOLE-NAME means match/replace the whole file name
+  instead of only the non-directory part of the file.
+Optional arg MARKER-CHAR as in dired-create-files."
   (let* ((fn-list (dired-get-marked-files nil arg))
 	 (operation-prompt (concat operation " `%s' to `%s'?"))
 	 (rename-regexp-help-form (format-message "\
@@ -2317,8 +2322,8 @@ Type SPC or `y' to %s one match, DEL or `n' to skip to next,
      file-creator operation fn-list regexp-name-constructor marker-char)))

 (defun dired-mark-read-regexp (operation)
-  ;; Prompt user about performing OPERATION.
-  ;; Read and return list of: regexp newname arg whole-name.
+  "Prompt user about performing OPERATION.
+Read and return list of: regexp newname arg whole-name."
   (let* ((whole-name
 	  (equal 0 (prefix-numeric-value current-prefix-arg)))
 	 (arg
@@ -2385,9 +2390,9 @@ See function `dired-do-rename-regexp' for more info."

 (defun dired-create-files-non-directory
   (file-creator basename-constructor operation arg)
-  ;; Perform FILE-CREATOR on the non-directory part of marked files
-  ;; using function BASENAME-CONSTRUCTOR, with query for each file.
-  ;; OPERATION like in dired-create-files, ARG as in dired-get-marked-files.
+  "Perform FILE-CREATOR on the non-directory part of marked files
+using function BASENAME-CONSTRUCTOR, with query for each file.
+OPERATION like in dired-create-files, ARG as in dired-get-marked-files."
   (let (rename-non-directory-query)
     (dired-create-files
      file-creator
@@ -2477,10 +2482,11 @@ If it is already present, overwrite the previous entry;
 With a prefix arg, you may edit the `ls' switches used for this listing.
   You can add `R' to the switches to expand the whole tree starting at
   this subdirectory.
-This function takes some pains to conform to `ls -lR' output."
-  ;; NO-ERROR-IF-NOT-DIR-P needed for special filesystems like
-  ;; Prospero where dired-ls does the right thing, but
-  ;; file-directory-p has not been redefined.
+This function takes some pains to conform to `ls -lR' output.
+
+NO-ERROR-IF-NOT-DIR-P is needed for special filesystems like
+Prospero where dired-ls does the right thing, but
+file-directory-p has not been redefined."
   (interactive
    (list (dired-get-filename)
 	 (if current-prefix-arg
@@ -2526,8 +2532,8 @@ This function takes some pains to conform to `ls -lR' output."
     (restore-buffer-modified-p modflag)))

 (defun dired-insert-subdir-validate (dirname &optional switches)
-  ;; Check that it is valid to insert DIRNAME with SWITCHES.
-  ;; Signal an error if invalid (e.g. user typed `i' on `..').
+  "Check that it is valid to insert DIRNAME with SWITCHES.
+Signal an error if invalid (e.g. user typed `i' on `..')."
   (or (dired-in-this-tree-p dirname (expand-file-name default-directory))
       (error  "%s: not in this directory tree" dirname))
   (let ((real-switches (or switches dired-subdir-switches)))
@@ -2543,12 +2549,12 @@ This function takes some pains to conform to `ls -lR' output."
 	 '("F" "b"))))))

 (defun dired-alist-add (dir new-marker)
-  ;; Add new DIR at NEW-MARKER.  Sort alist.
+  "Add new DIR at NEW-MARKER.  Sort alist."
   (dired-alist-add-1 dir new-marker)
   (dired-alist-sort))

 (defun dired-alist-sort ()
-  ;; Keep the alist sorted on buffer position.
+  "Keep the alist sorted on buffer position."
   (setq dired-subdir-alist
 	(sort dired-subdir-alist
 	      (lambda (elt1 elt2)
@@ -2575,7 +2581,7 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
     m-alist))

 (defun dired-insert-subdir-newpos (new-dir)
-  ;; Find pos for new subdir, according to tree order.
+  "Find pos for new subdir, according to tree order."
   ;;(goto-char (point-max))
   (let ((alist dired-subdir-alist) elt dir new-pos)
     (while alist
@@ -2594,8 +2600,8 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
   (point))

 (defun dired-insert-subdir-del (element)
-  ;; Erase an already present subdir (given by ELEMENT) from buffer.
-  ;; Move to that buffer position.  Return a mark-alist.
+  "Erase an already present subdir (given by ELEMENT) from buffer.
+Move to that buffer position.  Return a mark-alist."
   (let ((begin-marker (cdr element)))
     (goto-char begin-marker)
     ;; Are at beginning of subdir (and inside it!).  Now determine its end:
@@ -2607,8 +2613,8 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
       (delete-region begin-marker (point)))))

 (defun dired-insert-subdir-doinsert (dirname switches)
-  ;; Insert ls output after point.
-  ;; Return the boundary of the inserted text (as list of BEG and END).
+  "Insert ls output after point.
+Return the boundary of the inserted text (as list of BEG and END)."
   (save-excursion
     (let ((begin (point)))
       (let ((dired-actual-switches
@@ -2643,14 +2649,15 @@ of marked files.  If KILL-ROOT is non-nil, kill DIRNAME as well."
 	    (run-hooks 'dired-after-readin-hook))))))

 (defun dired-tree-lessp (dir1 dir2)
-  ;; Lexicographic order on file name components, like `ls -lR':
-  ;; DIR1 < DIR2 if DIR1 comes *before* DIR2 in an `ls -lR' listing,
-  ;;   i.e., if DIR1 is a (grand)parent dir of DIR2,
-  ;;   or DIR1 and DIR2 are in the same parentdir and their last
-  ;;   components are string-lessp.
-  ;; Thus ("/usr/" "/usr/bin") and ("/usr/a/" "/usr/b/") are tree-lessp.
-  ;; string-lessp could arguably be replaced by file-newer-than-file-p
-  ;;   if dired-actual-switches contained t.
+  "Lexicographic order on file name components, like `ls -lR':
+DIR1 < DIR2 if DIR1 comes *before* DIR2 in an `ls -lR' listing,
+i.e., if DIR1 is a (grand)parent dir of DIR2, or DIR1 and DIR2
+are in the same parentdir and their last components are
+string-lessp.
+
+Thus (\"/usr/\" \"/usr/bin\") and (\"/usr/a/\" \"/usr/b/\") are
+tree-lessp. `string-lessp' could arguably be replaced by
+`file-newer-than-file-p' if dired-actual-switches contained t."
   (setq dir1 (file-name-as-directory dir1)
 	dir2 (file-name-as-directory dir2))
   (let ((components-1 (dired-split "/" dir1))