From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Boruch Baum Newsgroups: gmane.emacs.bugs Subject: bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] Date: Sun, 25 Apr 2021 01:22:12 -0400 Message-ID: <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> References: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="pehdeew5grcqxr5k" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="10295"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: NeoMutt/20180716 Cc: "47957@debbugs.gnu.org" <47957@debbugs.gnu.org> To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Apr 25 07:23:20 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1laXEl-0002WL-U6 for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 25 Apr 2021 07:23:20 +0200 Original-Received: from localhost ([::1]:58244 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1laXEk-0001GT-Fg for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 25 Apr 2021 01:23:18 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46944) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1laXEU-0001GJ-60 for bug-gnu-emacs@gnu.org; Sun, 25 Apr 2021 01:23:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:58558) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1laXET-0002B3-TJ for bug-gnu-emacs@gnu.org; Sun, 25 Apr 2021 01:23:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1laXET-00054X-OW for bug-gnu-emacs@gnu.org; Sun, 25 Apr 2021 01:23:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Boruch Baum Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 25 Apr 2021 05:23:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 47957 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 47957-submit@debbugs.gnu.org id=B47957.161932815319449 (code B ref 47957); Sun, 25 Apr 2021 05:23:01 +0000 Original-Received: (at 47957) by debbugs.gnu.org; 25 Apr 2021 05:22:33 +0000 Original-Received: from localhost ([127.0.0.1]:41871 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1laXE0-00053c-A6 for submit@debbugs.gnu.org; Sun, 25 Apr 2021 01:22:33 -0400 Original-Received: from mout.gmx.net ([212.227.17.22]:54399) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1laXDw-00053L-0J for 47957@debbugs.gnu.org; Sun, 25 Apr 2021 01:22:30 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1619328136; bh=ObqNin8RYgAo1pWX3qd6+c7BgSoZY3LlzLj9XR2SY2E=; h=X-UI-Sender-Class:Date:From:To:Cc:Subject:References:In-Reply-To; b=dv7qdGNqRa78EOioRNGfvF54VFUpVct42YdFV9o9QDuZaBvV5l8Jlc9PI9M+esPZK eNOIukyYbqMp4+sVC8xSlxHMpJVapbncWXibB3jP+u+FNabXw02DRYAzOjPzI3KKyC 9Dtu06Sdwc6g9jOMWrOVKMXd37sceIjT7RdY/Q/U= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from E15-2016.optimum.net ([70.19.86.82]) by mail.gmx.net (mrgmx104 [212.227.17.174]) with ESMTPSA (Nemesis) id 1MPXdC-1lx03Z2oRG-00Maxk; Sun, 25 Apr 2021 07:22:16 +0200 Content-Disposition: inline In-Reply-To: X-Provags-ID: V03:K1:fwYDwskwPXi1HSg1we1mFc8utPf1a4CpH2lAUqUMZDcBSFbWmAO Pnq0FqiNxNcPP+rz7M2GKAqrt5ihyODjh7t/mxsbPpREsrkb5wr8riFgw8a85S7TniIsXO1 qntji13qeDMgAZlpFF3bN/Sxq5ZYw4THaW/D5Oblb/sB0KwJMrpfPhhbKT6VRUETFbLpSQ7 +F2s+y9q9SSiuf1wZaSNA== X-UI-Out-Filterresults: notjunk:1;V03:K0:QbmNaeyJVeM=:Erec1iZLLiBzy6Mjn63WbI lZsBhDNPIWlMxdEf2/Q9N5RaDB63Fg0uC9zb6B1lTlAFudV9M3UrtzEq54JVOuaat4zVWydSs +K/EHVmFpIdrNea7C6RIMrsQUDATK8DA3JFr+3oHTxsA1KaFf8I0o4k4n+yNfloAcI934u1bv Kgw223y0AXlzwARH5ZHaSh+cCRoBy4A33699VGMloW5sojtyGFEgIlipEo8inGAQSTseDNBN6 +SiQ+t0R+2ggwpcmZO53JwSG3rB/+O5VoQQpFfa+SSlzV0hchBD4ZsS8HzNeIdpse3fqZx/m0 vfwHZkyISORb6iv3fV32wNVISeQd8F9BPp2wdrhkhkN+De2yvYx+Ud87BRGPKnmjHUDUicaCq RyyfRwG9sjVSfD8mLP5HCHBzoGgy3zQuY1TM+izCM7mvpuaF5DBXk8TQwU6KF6QyGXZxnaGgM K644wf3nMqTBVLsBxQLmPMpsDFfD9G9BTV//wxxXkPKyCQRevbPJkdj/dp+pq4EDPKopRi3qD 1CVaHWN47YUCBzwdlL4ZR+OpW5ZuJlpD+Hjay8nLWeTKSytvWWTGaMdTuU1l0cRk3BCTVwnah INP5Hj43dxpQsuIVrUIsTjSkc+D6mGhZnD4gKVkN1EmoYaWtMK2j6g8VlGIDU2Nf11pAi4zYg No2h9SfTwig2RdyJrUZ+J81YzYY/U0jUvXsTLOEmQ1EAIj4SrnDzjjOg9XpVaFmR17WkxrXVU EfF43DlI+4lG5/aqeDn5BVZRxZLdzLMFBXWbdV+C23HqBIoXim29oNSHy8ti1PXDYUJOFYQW X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:204846 Archived-At: --pehdeew5grcqxr5k Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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. =2D- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 --pehdeew5grcqxr5k Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="dired-aux-2.patch" Content-Transfer-Encoding: quoted-printable diff --git a/dired-aux.el b/dired-aux.el index 3ee877e..dd5c27d 100644 =2D-- a/dired-aux.el +++ b/dired-aux.el @@ -314,12 +314,12 @@ List has a form of (file-name full-file-name (attrib= ute-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 startin= g 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 li= ne. -\(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=3D"" suppresses message. +To undo the killing, the undo command can be used as normally. + +Returns count of killed lines. FMT=3D\"\" 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")))))))) =0C (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-progr= ess) -; "Map FUN over marked files (with second ARG like in dired-map-over-mar= ks) -; 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 de= tails." (revert-buffer)) =0C (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 tha= t. +"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 v= ars - ;; 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 ta= rget. (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=3Dnil) 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=3Dnil) 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 targ= et. (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 ta= rget. 'nomini all-frames)))) (defun dired-dwim-target-next-visible () - ;; Return directories from all next visible windows with dired-mode buf= fers. + "Return directories from all next visible windows with dired-mode buffe= rs." (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 targ= et. (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-uu= decode @@ -2066,16 +2068,16 @@ Optional arg HOW-TO determines how to treat the ta= rget. 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 window= s. - ;; `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-fil= es. + "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 e= ntry; 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 DIRN= AME 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 DIRN= AME 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 en= d: @@ -2607,8 +2610,8 @@ of marked files. If KILL-ROOT is non-nil, kill DIRN= AME 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 DI= RNAME 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)) --pehdeew5grcqxr5k--