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

[Boruch Baum <boruch_baum@gmx.com>]

[-- 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))