From debbugs-submit-bounces@debbugs.gnu.org Thu Apr 22 15:45:24 2021 Received: (at submit) by debbugs.gnu.org; 22 Apr 2021 19:45:24 +0000 Received: from localhost ([127.0.0.1]:35589 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lZfGN-0004F1-70 for submit@debbugs.gnu.org; Thu, 22 Apr 2021 15:45:24 -0400 Received: from lists.gnu.org ([209.51.188.17]:52260) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lZfGL-0004Es-5A for submit@debbugs.gnu.org; Thu, 22 Apr 2021 15:45:22 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58496) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lZfGJ-0001mw-BF for bug-gnu-emacs@gnu.org; Thu, 22 Apr 2021 15:45:20 -0400 Received: from mout.gmx.net ([212.227.17.21]:57891) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lZfGE-00008P-K5 for bug-gnu-emacs@gnu.org; Thu, 22 Apr 2021 15:45:19 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1619120712; bh=VQY4NnEfWw1vVnL2ekwezKmTx6ACRhF6zuN2fL1NcSI=; h=X-UI-Sender-Class:Date:From:To:Subject; b=f137WL5Equ/e8Ze99H7Vl8UHA9B4GpcDdMLuHIvZL5jaZ2gnt8w6gDkqHdXVd/Rhe yzQDmVd/EaQojJ1wAhndcRpjkg1BVo8dfuJ3fmgqZwUJKoOfUbI4Bx3srkyQMXrafA Pf+YIZsn7/Pi27R9m7R+AiY6ABgbPsIODAPtEOQI= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from E15-2016.optimum.net ([70.19.86.82]) by mail.gmx.net (mrgmx104 [212.227.17.174]) with ESMTPSA (Nemesis) id 1MPokN-1lvqoW12kl-00Mrog for ; Thu, 22 Apr 2021 21:45:11 +0200 Date: Thu, 22 Apr 2021 15:45:08 -0400 From: Boruch Baum To: Emacs Bug Reporting Subject: diredx-aux doctrings [PATCH INCLUDED] Message-ID: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="52c2w5jabh66emb7" Content-Disposition: inline User-Agent: NeoMutt/20180716 X-Provags-ID: V03:K1:9ySKOhkWj20znx+mIKPyLjEJL/Xktc5YL6wmKrF5irOpGDMub1x J2DzNaUNIEu3xOVZh9ripnguCi1Zs4BukKayz9BUyoMXsD5Yv/xqWbzqgn3Czu++7kWmCmb U+KS76HUcJHhEkt0ZBfuyEFbpqpP+kuAWQHMOSf4ZaRaBiItjuRPd6dEJSGyCcivPRTa/u0 U58RqhJmYQXYLmT83D+rQ== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:4F7Oxo1Orx8=:MFAC/l4iFlCOPCNwuIVCOR Kams2umkl+z+q5lsfFuvUEZ45MhrWOZUMbsd3s2mfCL6OfIbVOmJFYdzK6ePl260A0XiPpnIz Yby1I8GhcglVrQ24qNcriDcVTzhok7Jyw5cw/7vc9tMyWOWPDg6OV/Jww0XJaNqAhcel7w5CI CnAEwxaUCTQ9A6bbjhI0xILLpGdgV6Kxb58EyOYAjFcWjvcbz+n/DhiOlihSHHGTyNrTeK+tJ +Xu7Ccauh7FePIAUJg98VdIY6O2zRhCB96qm6r4uFqIAPibakk5nlvyO4z2ITEIk5dhz/YFGo Ug7cR7YS/0iK1azuzcQev+hxmHKcMth0XnHpmF7Vkj14FXH32rtr8wpukpYndMxVvF6Zem/dd mOx+lG1DqzeG97me/It6C4R0ykewhOI5UTvMXkBCVMdKU6LZQHSNEBSLP4zRErU7CR23oflx7 XyjCJSUTU6igOKuYPOtpTf+7or9NKk+ponfmEJXevok6z70rHz3Z7pFjXYGjcH4ZxaSiuivi7 2UqJAF3DNjqlF4lM76BhUKaNl+eUaXbfEGLW7rGOHNdH75UZZ7A4ulfTTiFKTnwNeVqH4kdgq CSb0OtOuSrC/VYZDq2Wa/8SukOd1ea0gYzu7sh5Fhr/1FgucPJfdqhHlBu67v49ymu6MhFmWT kg4r4+Dw0sL85KU0u9asMKm3rH+yQxAn8m1WKol3JtcQABo1jjaKw+h+6N61ocvGh3U9QBEiu dWZncAZXvUgW8lC1wRFGRVNGFfy5zehQlbO6D8bx8QJemD8cFnanXxZiqM1M28WSo8W7GUR1v p7kPQlO4v3/bS6RnIX5H/0d65BY0X+EgPxZQDfBLeOYSFsdeq/PEAh6+1M9XrJtZJyMpKH8VQ 7p1Ibk8R2O0+qM60zV0ykCVt/xcDp6cv/eKs1T9m+7LoKxSjh+SPOZcQZFqg1Le+9ZQeeC4hY 13tV+IuCpoG7qD1nfiPtKxcFYH+NBzWs49GvXO/XaTML1P2Ik3m3PiEbsOcM+jCVzQegw1c57 iaYoRIhuTn8OXy+Uz8Vv4oRTQMBRwgbVCYUB/pCv52EF+FTgKL+F5kWbSSzvcVtj3BuZTSXNk Ihhd/ulMt64KayfghfHzCkSpBe+wGGF0++jM56zRXHepRuUw4B8BVkUB6k+FZ8Qhg2Py7VkB8 NPkxnSiaz76muM+5FtZhzsEySMLMWYwCvniawEIeyYnKaEllgMWgw/gf9paKmQBhoxMnI= Received-SPF: pass client-ip=212.227.17.21; envelope-from=boruch_baum@gmx.com; helo=mout.gmx.net X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.1 (/) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.4 (--) --52c2w5jabh66emb7 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable File dired-aux.el had many docstrings in comment form, meaning that they were non discoverable using `describe-function'. The attached patch fixes that. =2D- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 --52c2w5jabh66emb7 Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="dired-aux.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)) --52c2w5jabh66emb7-- From debbugs-submit-bounces@debbugs.gnu.org Thu Apr 22 16:16:10 2021 Received: (at 47957) by debbugs.gnu.org; 22 Apr 2021 20:16:10 +0000 Received: from localhost ([127.0.0.1]:35616 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lZfkA-00053w-6E for submit@debbugs.gnu.org; Thu, 22 Apr 2021 16:16:10 -0400 Received: from aserp2130.oracle.com ([141.146.126.79]:39164) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lZfk6-00053A-60 for 47957@debbugs.gnu.org; Thu, 22 Apr 2021 16:16:08 -0400 Received: from pps.filterd (aserp2130.oracle.com [127.0.0.1]) by aserp2130.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 13MKEEWs106247; Thu, 22 Apr 2021 20:15:59 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : subject : date : message-id : references : in-reply-to : content-type : content-transfer-encoding : mime-version; s=corp-2020-01-29; bh=zeDyjCGgAuy+0csNgV/GdDAeZrbSG2Znlfn/ZcofQ+s=; b=0QwPDrZnNHgRIZgT8I+M/RRbfT954ZOl0OqWUz0fzxjWaj0UKBAVfMpcFA9NIkIxWeZr qcLCHZ3vfcV+aI3yHkiIuQlHslIZEbwLXoQ62XGN1iKTiVLiyO35E4FmTzcMt+cNp7G1 Xac6zO89uFyUlGYr/9ORvLGkYtLoefGy9fMB5W1jMbegjj163q2avCaM8ZYc+y4mp+vj k3LF2VVqqVVjfwZJ8DovWxZReCg9IKYTduT53hVuAnfO/1Qg8dKJfRPu/bHTfNxTCEVt bQyHMFgKFBLKkl3CZywf7NrIq4W7qul7b0A8mNHC/5ux6VrOLAy/8ru0d7tbsw87TNRU tA== Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by aserp2130.oracle.com with ESMTP id 37yn6cen7u-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 22 Apr 2021 20:15:58 +0000 Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 13MKFN7J103810; Thu, 22 Apr 2021 20:15:58 GMT Received: from nam10-dm6-obe.outbound.protection.outlook.com (mail-dm6nam10lp2104.outbound.protection.outlook.com [104.47.58.104]) by aserp3020.oracle.com with ESMTP id 383cbdaa3r-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 22 Apr 2021 20:15:58 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=TVm+wNMKuuhAV1kDLF9VNxJJFy5okNo8QcpWPgdp/9ffIlK445p392ExRE0MSh2JaAoOzx++3IR1LnKMKVpwYT5B7+B5RpLkPSIU94+6NPv3YVCyaMSSPtvO9wsbPSvgOLGZO8vdpRhleBCLAVoz+5kUp+eXj1vythBiQ/VJz2EXkdvxToTOMFzTHuM1cQc/9HuDcjO9QDamzKvFxB5vtmT2QHYGD7QITHuvXPML1pfT71/hnEjBzFTuPEMtl7jTH1H/insARoycS2K0pEAsHQXeiI/WHh3vOud59yBsOhmi5EZJLzdDuYOhVCvp6W7USbeCevwX3q9Qi6F+nbqTTw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=zeDyjCGgAuy+0csNgV/GdDAeZrbSG2Znlfn/ZcofQ+s=; b=JIrIGeQxmL1chjijxQC6JEgnr/6LpO4fbv1MkPGgeIT0owj54+Gf6JOpYTSnHlrmgjlRnmEa4cmhZuS1JYlb/t5p49QM4lm69ZJL1fY6ppHEf0Vn80/ETlfABFfErmwxGNrdK9A6fGSZkCRdNlUthCu54XXIgCphSCO0iTmncICRHTgIPgX86huMmT6S/plyYPqb50X8gh7Mw7wS1eUT71kQlGW401zqFgP+y2SHMmoC5EasEfIAxZ5u+EIHkq0m6KJvWOShDSCCPhJLgOH3wvEDsDWeX0ZAW1Q+UJUxENr6ClG4h2azXVhFUNuymv0TFjnmf6NWvmU+5jqkvvdvsQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=zeDyjCGgAuy+0csNgV/GdDAeZrbSG2Znlfn/ZcofQ+s=; b=vD1poWN7NFEomddlUrhr2CJiPm7aC7XvCaTFbFELVOP1j4ugd7PrlstG7a8WSPD2bj/+F57PwJmKxWMlNI8mvUmbRC34mR55iOoD5Hk/FFmpgf0GGkM9sHE24N+clqV1SyFjwkEhMODQ7/9iCc3FuOhFWkQC9uwKfBVmiDOEXHw= Received: from SA2PR10MB4474.namprd10.prod.outlook.com (2603:10b6:806:11b::15) by SA2PR10MB4570.namprd10.prod.outlook.com (2603:10b6:806:11e::9) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4042.19; Thu, 22 Apr 2021 20:15:56 +0000 Received: from SA2PR10MB4474.namprd10.prod.outlook.com ([fe80::2109:9725:fd4a:6494]) by SA2PR10MB4474.namprd10.prod.outlook.com ([fe80::2109:9725:fd4a:6494%6]) with mapi id 15.20.4065.021; Thu, 22 Apr 2021 20:15:56 +0000 From: Drew Adams To: Boruch Baum , "47957@debbugs.gnu.org" <47957@debbugs.gnu.org> Subject: RE: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] Thread-Topic: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] Thread-Index: AQHXN7G9cFdwggJ+oE+joonSrC/qjarA9W5g Date: Thu, 22 Apr 2021 20:15:56 +0000 Message-ID: References: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> In-Reply-To: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: authentication-results: gmx.com; dkim=none (message not signed) header.d=none;gmx.com; dmarc=none action=none header.from=oracle.com; x-originating-ip: [73.170.83.28] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 2df17815-163f-4f91-af9c-08d905cb7016 x-ms-traffictypediagnostic: SA2PR10MB4570: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:8273; x-ms-exchange-senderadcheck: 1 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: gVq7bq/1n0jAr+Nyl9JPu3QxglgQajRKrbFkeah6bBCzAic0F1Kle9hz5aXRZ0TpjRn+RnAQn5AAHUtgzMN2mmnNuEaR/7XYWqtOggTRZKtAPL4t0Hxh/jzLplj/+kTUZ2/8J1UuAyYiMDuuoUJcxX6GVI/NLKKRebrOvHpVvxrcD2m5y50LkHaql7902rTSXy1bDtsQcVaA4ubbZBssNtkOY7SDfyt09no+HMeu6zs2S+XOgCLRLCkGZLxEaffGmJZ1WwhNUxWKSkgwrxV6ptOeF8wapIdada+YA6oyJ57bnIhBbKtBhWByp6Ky4+VNEw+jopHi+6FHl5WvKaiL9v31S39hxNljb+/qMecpAoETqStlR1BXTxnlhUoAS3cgB1R9DGw+p+Sc4HIqGR2WQhLRlmhtKkDZtgSYt8OpJFqH0tkGsQ3ojMRO+sOgqLEB3ZnP+PdXTRCcu7F6j85f8AT7yAWTU0HYJ1uYK1Fdxdcpm1+efAIShWSDODlloW5pc9HJWtazzSjci4woJM68XHUv+VP+WH1Pn9IJGebmv4zbPJqFuzwMFpi/G7RSDHJQdx9lyB8W5mzgvTZK02IOl1k5Z+sxNM7vsgO8Krf1Vs4= x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:SA2PR10MB4474.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(376002)(346002)(39860400002)(396003)(136003)(366004)(64756008)(8676002)(66446008)(44832011)(122000001)(478600001)(26005)(76116006)(83380400001)(316002)(66556008)(52536014)(66476007)(6506007)(66946007)(86362001)(38100700002)(33656002)(7696005)(2906002)(5660300002)(186003)(55016002)(8936002)(110136005)(9686003)(71200400001); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata: =?us-ascii?Q?ziv1xV+tKsaPzacUF63X5UBDfpniuZMK42i3z49WUqBLrDhGlo9wxnkJJiQy?= =?us-ascii?Q?yYXyNjkfhA/S6Lc3GJMNBrv/Excexth/0UTfW2VNkCPnNTmzRbHoEnYGXZ6E?= =?us-ascii?Q?Iuoh2Ffsj7K8rEHUG3g5hfbjKhUxXPKp36hhyI9wUUy6gopbdq1SmxNWdJYb?= =?us-ascii?Q?XhVnKbW+2I6Pf1eUK2AwXmMTull89CdYxVXYz/vHhpTGbrAzcrtgtWhKZzY8?= =?us-ascii?Q?4q4FGnekDfr/Rw1BQRa+QQAa7cC4rFOpy65RmRuHW8NQhG2tsttdbNhUCDBS?= =?us-ascii?Q?NacUIhVSJfQmIETnzxiqq/wS/3+COspT08R9QJ0yz2HmE98RZ9Wk4xKWiwlK?= =?us-ascii?Q?DbEOY/rHHwY/Csx30IBFJS0H6t7K2Z+zLPB/g+1sgDot7pVHXFGLuTjNCJpy?= =?us-ascii?Q?UoHbk4CoiCyyDDeGbbqKfnvkuYLot2FBZUdScyfGRDrjXpepbzV3M2oFT8zv?= =?us-ascii?Q?Dt339HbisFdF95l6ai23NIYsS4ZqJuTv6CXnCwuCpInGDB4VVRawEQrDpNil?= =?us-ascii?Q?r86nj/hIryd9IL99kyGe/yLIQdvI2cA+eVCyvXXiGBWugVjnnFYWHf9WFHdF?= =?us-ascii?Q?HNXQwuseksr6K+izJkxbj9p8LJZ5n2FWhYWILpRM4l7d6CThmFHDgwPMiYex?= =?us-ascii?Q?UEhDT8eCyPJN+YM7lvj2O5853wVR5U0jxbqhTpx542TZ/kZyn370ysaWrfSJ?= =?us-ascii?Q?k02+ITSWlTguW5o7WBgaWW+AiCj5pQVnGV2WSngz0cSl4yuWkwYYkgqDjjwz?= =?us-ascii?Q?DoexXt6ItItvBICzJ29dDgG96NLKOr2dP+95CGbv8dA1KQ/+1cQIeIbtmlF2?= =?us-ascii?Q?K6sBKs1fzrdTFoa2jB2XqbVpaAGw3aVMHLtDfRPKwx0c5zKlL4bQfygt/po1?= =?us-ascii?Q?dN9MTu0o4/bMSNwtDt2nRVg8zvH7AlWsjIEawShGl7NpsTNnbef93YzJyvwS?= =?us-ascii?Q?YMlcpZkcNmtvYY2TNekblnipKqb28dFO0f3loHMKQKAIJvMVchybfkvLiS4L?= =?us-ascii?Q?CwaaUZeBBsycrIqgWB4s99Y7b1RBigpAfpibqIpMFqZ/IaA9gbn1nk+X3Sin?= =?us-ascii?Q?h5HS5rEmfjuRShkZMmIG8rGVE7s9ZlpF+Iq+TANOqyUgLIMORm/ClW28OswG?= =?us-ascii?Q?YF4bsYN4FH+y2Kbq2YrgCGYBH+RG9DyD5FJjSvigFgHHReFW0buXUXHOcnRz?= =?us-ascii?Q?kybWL35NU2uAGXwbZnppXUAkJED9pQPBb6UbKSFeQzfEIcmjEv62i4GAbqFM?= =?us-ascii?Q?/kdWezjDIThVJzqkU62BEGd5HP7+A5bxdFuIkqdwNZszU4IuKpv9cw05wW5X?= =?us-ascii?Q?UdVodvy3ZK5H9QHIJvEYh14O?= x-ms-exchange-transport-forked: True Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: SA2PR10MB4474.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 2df17815-163f-4f91-af9c-08d905cb7016 X-MS-Exchange-CrossTenant-originalarrivaltime: 22 Apr 2021 20:15:56.6182 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: J4bCo5STxvi5pxcYvK0mQbAAkO3aKnRLreapNCeX9At3Vbtx2YTzKWY/dQt4g3CFbhCljHlodymL+z487MjM3w== X-MS-Exchange-Transport-CrossTenantHeadersStamped: SA2PR10MB4570 X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=9962 signatures=668683 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 malwarescore=0 bulkscore=0 mlxlogscore=999 phishscore=0 mlxscore=0 adultscore=0 spamscore=0 suspectscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2104060000 definitions=main-2104220150 X-Proofpoint-GUID: JUYZN8ETt8-vKeYsmqjUJC7R-9l1JMHp X-Proofpoint-ORIG-GUID: JUYZN8ETt8-vKeYsmqjUJC7R-9l1JMHp X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=9962 signatures=668683 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 malwarescore=0 priorityscore=1501 bulkscore=0 suspectscore=0 impostorscore=0 mlxscore=0 lowpriorityscore=0 clxscore=1011 spamscore=0 mlxlogscore=999 adultscore=0 phishscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2104060000 definitions=main-2104220150 X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 47957 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) 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 \.) From debbugs-submit-bounces@debbugs.gnu.org Sun Apr 25 01:22:33 2021 Received: (at 47957) by debbugs.gnu.org; 25 Apr 2021 05:22:33 +0000 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 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 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 Date: Sun, 25 Apr 2021 01:22:12 -0400 From: Boruch Baum To: Drew Adams Subject: Re: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] 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" Content-Disposition: inline In-Reply-To: User-Agent: NeoMutt/20180716 X-Provags-ID: V03:K1:fwYDwskwPXi1HSg1we1mFc8utPf1a4CpH2lAUqUMZDcBSFbWmAO Pnq0FqiNxNcPP+rz7M2GKAqrt5ihyODjh7t/mxsbPpREsrkb5wr8riFgw8a85S7TniIsXO1 qntji13qeDMgAZlpFF3bN/Sxq5ZYw4THaW/D5Oblb/sB0KwJMrpfPhhbKT6VRUETFbLpSQ7 +F2s+y9q9SSiuf1wZaSNA== X-Spam-Flag: NO 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+C23HqBIoXim29oNSHy8ti1PXDYUJOFYQWN 9W9tDmQZt0QeVws+2/+zSeEaqOCta4DoCg0kRtvsawdKUuFPz0BSzBo5U7HlXgYKSTUHUJZiq KSRgnW6mGgriEgXCKVDJs4KtFqyZZn83jkSwK5RsfU1EIp8fJ7vF2WtXM9n2QRNw2Bl91QGIo CFfRM4L8ss/7u6d9zx2VHmhdyT3pBGb2uo74Ehl52jsc3snYMEbJpoakDlsxkS+VqPBRkXwHQ RN1ynsSqKYxlmLKTUUyrsEXXUZrAzq/daV+/8Rkhg2P2meB+D6ImMJKe6+Vtk1eqCpk0QThUe XqRpSNyN+/y8kbcTS9bcHuGzSgQbCzyMj7h37gCDZI3EH7tklqv0oBv9j1DimnlbSlgsozEaj lxrbNJ/6WoAUuWuu1RKscd/vJUhT8QpGgJNtt2iW6qmuMHwmZ+HxrRtz8ZU6QUTupjJcE= X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 47957 Cc: "47957@debbugs.gnu.org" <47957@debbugs.gnu.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) --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-- From debbugs-submit-bounces@debbugs.gnu.org Sun Apr 25 04:15:52 2021 Received: (at 47957) by debbugs.gnu.org; 25 Apr 2021 08:15:52 +0000 Received: from localhost ([127.0.0.1]:41941 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1laZvk-0000tw-C8 for submit@debbugs.gnu.org; Sun, 25 Apr 2021 04:15:52 -0400 Received: from eggs.gnu.org ([209.51.188.92]:58562) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1laZvi-0000ti-6Z for 47957@debbugs.gnu.org; Sun, 25 Apr 2021 04:15:51 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:34245) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1laZvc-0000Tv-Qu; Sun, 25 Apr 2021 04:15:44 -0400 Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:4151 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1laZvc-0002W1-7R; Sun, 25 Apr 2021 04:15:44 -0400 Date: Sun, 25 Apr 2021 11:15:23 +0300 Message-Id: <83y2d6lqzo.fsf@gnu.org> From: Eli Zaretskii To: Boruch Baum In-Reply-To: <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> (message from Boruch Baum on Sun, 25 Apr 2021 01:22:12 -0400) Subject: Re: bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] References: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 47957 Cc: drew.adams@oracle.com, 47957@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Date: Sun, 25 Apr 2021 01:22:12 -0400 > From: Boruch Baum > 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. From debbugs-submit-bounces@debbugs.gnu.org Sun Apr 25 05:12:30 2021 Received: (at 47957) by debbugs.gnu.org; 25 Apr 2021 09:12:30 +0000 Received: from localhost ([127.0.0.1]:41993 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1laaoY-0002Ey-GJ for submit@debbugs.gnu.org; Sun, 25 Apr 2021 05:12:30 -0400 Received: from mout.gmx.net ([212.227.17.21]:37459) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1laaoW-0002Ek-8g for 47957@debbugs.gnu.org; Sun, 25 Apr 2021 05:12:30 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1619341938; bh=6OyOUdN6IC+F134V9vyl5bpNLCNYx9psDxtFbQLmsV4=; h=X-UI-Sender-Class:Date:From:To:Cc:Subject:References:In-Reply-To; b=EplLsonLBRX4KhOhqngU50g8uHvHJS8D3ZKGXADRUuxQZ3OPIKTDqquFEJfUH+xhn VNWbT0LRA9F5GpWsZ7rwVUwJt2G+47SNUqzvCGn1RiUrfsYT/sZK9JiqyEZfc4/1xL Zbd+zLHjTlCLkarAHwnWsg+NqqBG/nhF/blRXWlg= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from E15-2016.optimum.net ([70.19.86.82]) by mail.gmx.net (mrgmx104 [212.227.17.174]) with ESMTPSA (Nemesis) id 1MPGVx-1lxTup0CTd-00Pc59; Sun, 25 Apr 2021 11:12:18 +0200 Date: Sun, 25 Apr 2021 05:12:15 -0400 From: Boruch Baum To: Eli Zaretskii Subject: Re: bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] Message-ID: <20210425091215.jctkznunn4re7su6@E15-2016.optimum.net> References: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> <83y2d6lqzo.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83y2d6lqzo.fsf@gnu.org> User-Agent: NeoMutt/20180716 X-Provags-ID: V03:K1:Uq4PuuvAwds0bbUEJ5pz8MpgKrfpKxChVcsKpxQdMVvegtGToSA NL9x74pmtWKwvprzf0sJMu0806ov2+NZATV8iU/VWzS0Z4T6wPzdwmaU2CrjI6WAxdA5D2V 3vImthZCTYtoBntmhmts1gxni6KSOnGCm5ztWxlUlO1jaAZaddalOuN/1FMyVl0cm51sBX/ M0qEsfdXx4V7yIu0hsVKA== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:7xwWOc4JyP4=:O5Wd2wtFBFcTX4qrwdN8OR 7rgW9r3UBy4ZgxnLWxTtS6+qMI2Q5ViIS1FVakWRD34rMTyIdgROGAfJ14MRr6kS/qm/VFDzT 6ZiqZ9643wGZ+N5/2qDo+axnVj3iJfDwhXmKolwPqNazpdu5O2Lhm9P/gFN7CXFxqoNSdZ4Ok kK5fk4u/EBhzTbRLcvwGeXksRAtLB/HF8qQKL05ppEZ73e+7pP1sQS6txREQaxP9wuhP35h8g 5DtItm139DrZCyjxWURL/vNxyAJKbyCr7zhOj+MNxpb4P1ryUnG11DI6Wnl5GfduQ+mZQxh3j 1HWwWk1LKqlsv/4oZIiOy6rinY8p6Vu9n9HDHWAs7cjoQuyHEeBoO0hud5khYt2IdeIkwcFiT bi7rasrVbaOBCDewWyWUGBLgTsDQnuQ4J3S9ybyMo9HJuUI/Mie5Aq3fRt/AQQ6hU0Un4q6i3 9XIH4VZ82CeFUTtnSjPZGc2zkL4NaXFTLrZzi8TQsmDYubRqvHKzzyL2wAkG+hcZFGy22oe2G 3E6k/7YgnHSG97joGsLbGBZ7ksDOxZFrQQWev4T9a4ccIGXysndIUMYT1oiC/VV6ePNMOu7Sy Mk0LZmhG7NU/szru+9jNGFz7msW4Xth5Pi96E+fpW6qzQ9lKrwfUPKzaJSIsH4WkMEOqIqeBw ZJ1lfCYe2RIrm6i3a5rgGnxLVB4+82F0XW8zrkVzHNxWjoKae7w/6DtXvfiY3gFAUoVZHg+Ah kmXNR2Hdh4etCuV5WFaatnfT+xvWBNPTu5IqsNs6/BnvtRXTuoow9PUdA9VU5td7WMOoirZ/C AdBB3aUg1fMFG0XZQJorbVpRiKtzdzsHokFEwHzrK9WFdBV4yuurkwOkjt0VStrXNfmjD0X3Y phqYYQh5+30aJSBbhzrCfxKJa8GDkl6rBG5hvlzkTxsP+PhYh7E8bJutL0yCOEx5M9X84XsbU T6JVYATLMvozQ3P2M0zPYfrfKu81G3mw9uxIFH7a1iqn7O2pD6Nlqx+2dsf/u4pRveea6bxTC o2QlkkCIG0VDtmzbBj5tEG/RlBOqXCEj9Xq450gWwC9WjF1ydtlfivr+4k3Uk9PNfzXbjqi40 t22OWtzwxPwyLNz4jIQHhIncvpofJL/hTr8dmYltsatFA1fKDLK6tMCsi7xgdVACC5WvILbup /VJiePHlydMALSH2uceDkE+V71V1y4ivtnLhsZwqUc5n2uGoLU9BzTNMIh+nuvrAfRbLU= Content-Transfer-Encoding: quoted-printable X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 47957 Cc: drew.adams@oracle.com, 47957@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) On 2021-04-25 11:15, Eli Zaretskii wrote: > > Date: Sun, 25 Apr 2021 01:22:12 -0400 > > From: Boruch Baum > > 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. =2D- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 From debbugs-submit-bounces@debbugs.gnu.org Sun Apr 25 07:02:10 2021 Received: (at control) by debbugs.gnu.org; 25 Apr 2021 11:02:11 +0000 Received: from localhost ([127.0.0.1]:42091 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lacWg-0006zQ-Lq for submit@debbugs.gnu.org; Sun, 25 Apr 2021 07:02:10 -0400 Received: from mail-pf1-f175.google.com ([209.85.210.175]:35832) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lacWe-0006tx-V7 for control@debbugs.gnu.org; Sun, 25 Apr 2021 07:02:09 -0400 Received: by mail-pf1-f175.google.com with SMTP id c19so1178529pfv.2 for ; Sun, 25 Apr 2021 04:02:08 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:mime-version:date:message-id:subject:to; bh=xNe9ZPBvnPxSBU49KJ2SqW5elW9zmZIgF5gxf+ZadEE=; b=oRjCC9zp/SUx5c0XvXoMGPSO5fldCQFYmNY2sAvUDL9KIWx0L+ZaHVtjdcVW0xLB9X OSzXxUVk3SMPjSQaqrzi++uG1BvqWrRJoe8DChebqjPju7y9FIH6uYlIypitNq2/34b0 zpjYxyTrIwPQNTTaMkXtqmPYuEzpRm9gHgw3Ffls3C1Nz/oEiuBjrGFDzGXCjIBWF9Ev uJ68jrULSyMAo1Jp3AjoGA60EkqOkE69fX3qwQ31GusAkVzY7CxTJ6lSoVloCV2m9ADi R8zEcR4V+Qo/YvbQnvbsMx2icbTH55pqyDeBBQH4L3k/GsR1yaedpON1Yw3dHWKNnLoQ E62w== X-Gm-Message-State: AOAM530ewQ97xEgDn/XfiykmAPWkNmLDUSporyzdbz6w90Bx9jCbo0LZ pM9BVr6vxQpCDAgUlBYtAFNvey7YfXOhQrqm6Go7JLF0 X-Google-Smtp-Source: ABdhPJxcafKVTBwFSHxxWFneMRZM3u802VpUgztqfDW20JB/WKzeh8ICvshqUMmvG+AwJJ2plr5Vo9HjMxxdsoTWqmo= X-Received: by 2002:a63:a16:: with SMTP id 22mr11937847pgk.345.1619348523194; Sun, 25 Apr 2021 04:02:03 -0700 (PDT) Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Sun, 25 Apr 2021 06:02:02 -0500 From: Stefan Kangas MIME-Version: 1.0 Date: Sun, 25 Apr 2021 06:02:02 -0500 Message-ID: Subject: To: control@debbugs.gnu.org Content-Type: text/plain; charset="UTF-8" X-Spam-Score: 2.5 (++) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: tags 47957 - patch retitle 47957 dired-aux.el: convert comments to doctrings severity 47957 minor thanks Content analysis details: (2.5 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail provider (stefankangas[at]gmail.com) 0.2 HEADER_FROM_DIFFERENT_DOMAINS From and EnvelopeFrom 2nd level mail domains are different -0.0 SPF_PASS SPF: sender matches SPF record 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record -0.0 RCVD_IN_MSPIKE_H2 RBL: Average reputation (+2) [209.85.210.175 listed in wl.mailspike.net] -0.0 RCVD_IN_DNSWL_NONE RBL: Sender listed at https://www.dnswl.org/, no trust [209.85.210.175 listed in list.dnswl.org] 2.0 BLANK_SUBJECT Subject is present but empty 0.0 UNPARSEABLE_RELAY Informational: message has unparseable relay lines 0.2 FREEMAIL_FORGED_FROMDOMAIN 2nd level domains in From and EnvelopeFrom freemail headers are different X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 1.5 (+) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: tags 47957 - patch retitle 47957 dired-aux.el: convert comments to doctrings severity 47957 minor thanks Content analysis details: (1.5 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 RCVD_IN_MSPIKE_H2 RBL: Average reputation (+2) [209.85.210.175 listed in wl.mailspike.net] -0.0 RCVD_IN_DNSWL_NONE RBL: Sender listed at https://www.dnswl.org/, no trust [209.85.210.175 listed in list.dnswl.org] 0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail provider (stefankangas[at]gmail.com) 0.2 HEADER_FROM_DIFFERENT_DOMAINS From and EnvelopeFrom 2nd level mail domains are different -0.0 SPF_PASS SPF: sender matches SPF record 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record -1.0 MAILING_LIST_MULTI Multiple indicators imply a widely-seen list manager 2.0 BLANK_SUBJECT Subject is present but empty 0.0 UNPARSEABLE_RELAY Informational: message has unparseable relay lines 0.2 FREEMAIL_FORGED_FROMDOMAIN 2nd level domains in From and EnvelopeFrom freemail headers are different tags 47957 - patch retitle 47957 dired-aux.el: convert comments to doctrings severity 47957 minor thanks From debbugs-submit-bounces@debbugs.gnu.org Sun Apr 25 14:21:18 2021 Received: (at 47957) by debbugs.gnu.org; 25 Apr 2021 18:21:18 +0000 Received: from localhost ([127.0.0.1]:43739 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lajNd-0003dC-Vr for submit@debbugs.gnu.org; Sun, 25 Apr 2021 14:21:18 -0400 Received: from aserp2130.oracle.com ([141.146.126.79]:41812) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lajNc-0003cz-Ff for 47957@debbugs.gnu.org; Sun, 25 Apr 2021 14:21:17 -0400 Received: from pps.filterd (aserp2130.oracle.com [127.0.0.1]) by aserp2130.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 13PIL7Il133109; Sun, 25 Apr 2021 18:21:07 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id : references : in-reply-to : content-type : content-transfer-encoding : mime-version; s=corp-2020-01-29; bh=qCrCT3R4HXcR0/bUZnsrvc2kUnHnPi6N3Re380HONuc=; b=L5Uzxl1IsrbMy1WDpSMjD63HaZn6rzUgypz14KBgA5PFhOmkVG3Xe94BBolGHGw9BOsl +R/MiQhaThYrpY148GbSuhW3gk8nVA/UcJNpKIJIaaG7JPEtcD3/hmTWA6ZD46LAQZh3 mY6hfBeS62iHYSfOt//ttiUVpZ5MzBWpcY+zJVkaFBLvb4YPOtJYUvTNO/keu9Qwt7Pl FAKdd6usY+2LOEfde4uNOsFunrtlbFjt1EAzhZP6fzrsjLv9lPQmB0OUDXLBaudFFtfJ tdjwJKPlT8GuGIL5ijPyMUEEwMeRzpMLZTxiXbPVXU/AU4ZmAScO+6OuDZvQLAvX6Fm5 OQ== Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by aserp2130.oracle.com with ESMTP id 385afpr57w-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 25 Apr 2021 18:21:07 +0000 Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 13PIGDPe008225; Sun, 25 Apr 2021 18:21:06 GMT Received: from nam10-dm6-obe.outbound.protection.outlook.com (mail-dm6nam10lp2101.outbound.protection.outlook.com [104.47.58.101]) by aserp3030.oracle.com with ESMTP id 3849cc3mn0-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 25 Apr 2021 18:21:06 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=DAf6q5CGcr8PUsi1m3zu+vg1FyvCLBFvlaaF/qv5+0mAwkDlA4tSu/8NJEinSH1bkGdIsZCKpmY4PbBToHu83nLpVSbm/oZ0a44nacVHBx1VoQ9w3tBkWzzqsmSNNHmCGOSqbPqdag+VaA75KpL1z9VTwgVoLy6A0K3WmOajVy4cFCacX0WYt+bwuG8af8SnucQX7YIzO3vk0R+AgQ1UKqYoQb4xigQ9zX7OEuQP9o3iHxiIJ3r0XRjKhjd55NnYm4E9/VgC0RTdMv4H4R+q9oEqiIp8cypcoeq8ajMzX55/9ZAt6zru+VzWUKpkrKR7zKUQHzy1MCJcg1f1oVIHDw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=qCrCT3R4HXcR0/bUZnsrvc2kUnHnPi6N3Re380HONuc=; b=Fz/Wi06Nfmzq+TadQXXO57qfEyWs2RlFOm1+tv2AuFDnTRHAusXBmk1IFdk2ArYlI9yKIhCaCSG6uO+sv4VFLf0OPabfcHlqA22UqWLUCx5tLCeMIc51V17FdfmpG20dMXjW0K6BJd06LB5aC/LmrfVDVTBJfi1ioy5xD+UTwmOnl90URcw8nJONj/DMjCe7vqkrJOqyDpAbd0bEktuC6ZR1RRc66MDz+kY7I1robSu0TmIjxkJQxc8d6QMtFKlTjbRuxOVGUTR7e3dH2Zy0iN+Bpu/QUPp/+E3k29h+AxfSb40wkL1AJRoBCErc8T0ACJTgDnxvAvrG859LyEqRJw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=qCrCT3R4HXcR0/bUZnsrvc2kUnHnPi6N3Re380HONuc=; b=M7aGWqJ9QO7cs6J/EOSiyPMALxtVt21MW5UQS0+8Z8oYUxwQo3mN9Oxdh/laTwEPX5zUfcUJrq7rgN+EU2u7458lbLkSxq3p5yL0vRdP88YZyZjrJPSzafL4epS3V/L+5i6vzuIuFtQqQPdemZ14bw5iF2S2xgIhs3zVR3e5FFk= Received: from SA2PR10MB4474.namprd10.prod.outlook.com (2603:10b6:806:11b::15) by SA2PR10MB4780.namprd10.prod.outlook.com (2603:10b6:806:118::5) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4065.23; Sun, 25 Apr 2021 18:21:04 +0000 Received: from SA2PR10MB4474.namprd10.prod.outlook.com ([fe80::2109:9725:fd4a:6494]) by SA2PR10MB4474.namprd10.prod.outlook.com ([fe80::2109:9725:fd4a:6494%6]) with mapi id 15.20.4065.021; Sun, 25 Apr 2021 18:21:04 +0000 From: Drew Adams To: Boruch Baum Subject: RE: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] Thread-Topic: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] Thread-Index: AQHXOZL54roEzmPrbEulSkapgJ2a16rFbQdQ Date: Sun, 25 Apr 2021 18:21:04 +0000 Message-ID: References: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> In-Reply-To: <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: authentication-results: gmx.com; dkim=none (message not signed) header.d=none;gmx.com; dmarc=none action=none header.from=oracle.com; x-originating-ip: [73.170.83.28] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 067f36b9-d957-4c4c-d7df-08d90816e375 x-ms-traffictypediagnostic: SA2PR10MB4780: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:10000; x-ms-exchange-senderadcheck: 1 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: 4v22M//NeKEDwS5CZgr5zpmJIoHXsz+4lst6nrHhOqa1moLv9R6ewwgew0V0mb8JI5M7s5F4YUnc3B/N51riffenhiF5ewddvDjUnVOsl2Di8HjXx4ki3U15CfMnlUgsbaazEGBpNyNaewyrZqQB3DUlkpJTVtWMCR7TUlG9Yui492Ht4Lsz2PNGaPSM1ArAbskbsUQ2WXj4rRFl4apAzjQ7C+pV6VVtfa/jiwv66e0/bOiRHUDEccBBHJM0C7bC0VkLhxsAI3KOlbRiqRWigaIoOibeZzSLx6tbwbPGX3tpQi0Rxi8937Jp8LYXBL5VgPfXGTJL4TNvadVd2dlZQhzikqYoh4oTUgukTyt4HV6p1GyJKeohkK0jQIxN99sKRsqHF0kF0gq01aZ3/oj79QiWOEEl1M7wSVMi9z83jZhE4ILIOdRbWkM4IFuAvMgJJHdDxnQEDnW2AkuOGR18lnYFPEwgUHVZnSY7FXBzn/VEtjji3gIsSq8L0UGhNa28NrDxaBaHeJitT61RrmRsproUcA5QkfhwvxBfAR+WHDNaGb4L2vlzh3GePZEnCjvCaHJR/pV4e/Ycqap/QYm0UnZ3SAj4IZNYDsA1nrrvHAY= x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:SA2PR10MB4474.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(39860400002)(136003)(376002)(396003)(366004)(346002)(66476007)(8936002)(66446008)(66556008)(6506007)(2906002)(64756008)(6916009)(7696005)(66946007)(76116006)(44832011)(52536014)(4326008)(8676002)(316002)(5660300002)(71200400001)(33656002)(478600001)(38100700002)(26005)(122000001)(9686003)(86362001)(186003)(83380400001)(55016002); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata: =?us-ascii?Q?e/yvuPNe710cNd9dytjQMNyKkBzghCpI6KWFGEiID+wGBfcHMkp07hMROFpR?= =?us-ascii?Q?B0TQ+NXBygc/XLSMPyT7o139tB4HqpnxihecgFdsQBHdwLbP5vdjP0JU1kqk?= =?us-ascii?Q?LzeQTEVWHl39Klwsmada5vkyYQdkkMyMKNgt6mNEd5F5OBhkbLBQwq+zwxsw?= =?us-ascii?Q?QILcUHe8zaurLUD/zvlC4eaSKLgb7P5pBSVWXKE1aJSI1L3wxd3VrOecsotz?= =?us-ascii?Q?b0pY0wNKIQlFtNNrP+JQcn3D/WC0MmvE2OtAGmAoAz+0PzD5A9DZj7d+J4t1?= =?us-ascii?Q?hriopd0FKARa8WZiVraKa9uMc7+a3iOsVF3lngrobTtfFSeY20BGykfWm01F?= =?us-ascii?Q?63LzhA6ebCmudwe93r/C29crZsdoL2pku/0T5jfBib2SjGfuJu8qAjDzuEJl?= =?us-ascii?Q?NTItJ6F+5v+4la58n96w8DUQLovQh8K43zTxod2IlKxgmOFcQ6O/gg5OLS8N?= =?us-ascii?Q?+427e4rU+jyfAh6EaF+q/LA1jmAbvSmYC3QRSkm7jw8b7HzJn9pKrt8pllb4?= =?us-ascii?Q?zkihPrgtwJlD8zZbBZRXhk0BrCtNtjXHpYo5zCLrZdHBDwM2OCUQ8qKR+gxj?= =?us-ascii?Q?/IS5hg6dnhzDmrbrE2bXhDOixlM/WAps2kcw2RXlMJOb0402iQYK/xOZrw9U?= =?us-ascii?Q?6w/zAKvtLx4o9OJgI2TkkkZAU0rzfgpsQo2VtLqs573XHIY9Szu6On6fACW/?= =?us-ascii?Q?TwRVjNxZCVGOXP4ZxJ1RV9XjfzxYrNcEw+eNDAiVh6Vk7gwv+pXJB7Ue64c2?= =?us-ascii?Q?Aw9kX49JbJKVRKTsBCFlC2sZNRJrnYLRQ7myguPZXzhYowzTrbGrVw63gVu5?= =?us-ascii?Q?kTWCP5N+/LffI0QMzZI/1bDybmUhxTc0Jje0lkLNXSdRBmxZ6UZEdyTZjDNm?= =?us-ascii?Q?QUCZLlccxvRgBkZZ9TQlpnyu34g7iUnIEmb2+V76Jsn/5eHnTjbYy0SkqudZ?= =?us-ascii?Q?2c8vySoIsf3FctCkdDqlndqIVuHoUGQ09yDI+690HES7UakZgJ9ElkXhDcth?= =?us-ascii?Q?20t8VrEYtndv+08KtLzP6cXCpe9cXJfj+ihWfOMoUdf/IIiRDUc5N8znIWCr?= =?us-ascii?Q?yrFGB7hxSxPmkxko7ewH/OrCifa8dbZzkxHvUiWAOl+Z36mpx0Y5H22IRgj4?= =?us-ascii?Q?sJDvoz0NHOt0udF4r7r/bl3Hj1a6NwSRRUUvIdInpSOo9qCKPgkcelL0pwMK?= =?us-ascii?Q?7mkPZgJJI9d3WtkNhxoQhY4eqd+9W13K5rJO8+5gTWfst6inUboRI0S75AVM?= =?us-ascii?Q?cNfX4WBYfiTCnyOAzkAxC031FRPnzUtgrtjPprVDQpUF9Uyz51sthYu27Q0k?= =?us-ascii?Q?Rk42G7ARbdgGjJdb30ZU+gYX?= x-ms-exchange-transport-forked: True Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: SA2PR10MB4474.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 067f36b9-d957-4c4c-d7df-08d90816e375 X-MS-Exchange-CrossTenant-originalarrivaltime: 25 Apr 2021 18:21:04.6526 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: LDXgFi2Pid+Nl3TPJVCkQQSvQsltaXH1bzivXSOAKA1j1EWjYbpHxAlCKaPy8TNcL9/v8bSvhr0yNccx851DSg== X-MS-Exchange-Transport-CrossTenantHeadersStamped: SA2PR10MB4780 X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=9965 signatures=668683 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxlogscore=999 suspectscore=0 adultscore=0 mlxscore=0 spamscore=0 phishscore=0 bulkscore=0 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2104060000 definitions=main-2104250139 X-Proofpoint-ORIG-GUID: 15xxqR4BgGqGzXSLzIyECHa8k3pfs4BC X-Proofpoint-GUID: 15xxqR4BgGqGzXSLzIyECHa8k3pfs4BC X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=9965 signatures=668683 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 bulkscore=0 spamscore=0 phishscore=0 clxscore=1015 suspectscore=0 lowpriorityscore=0 mlxlogscore=999 mlxscore=0 adultscore=0 malwarescore=0 impostorscore=0 priorityscore=1501 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2104060000 definitions=main-2104250139 X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 47957 Cc: "47957@debbugs.gnu.org" <47957@debbugs.gnu.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > > Thanks for doing this. >=20 > Quite welcome. Let's see what it takes to get merged... >=20 > > 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 \.) >=20 > 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 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=20 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=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." 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 buffer= s." Return a list of directories from visible `next-window' Dired buffers. =20 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. From debbugs-submit-bounces@debbugs.gnu.org Sun Apr 25 15:39:01 2021 Received: (at 47957) by debbugs.gnu.org; 25 Apr 2021 19:39:01 +0000 Received: from localhost ([127.0.0.1]:43871 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lakap-0001Pc-Lz for submit@debbugs.gnu.org; Sun, 25 Apr 2021 15:39:00 -0400 Received: from mout.gmx.net ([212.227.17.21]:38571) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lakal-0001PM-D7 for 47957@debbugs.gnu.org; Sun, 25 Apr 2021 15:38:57 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1619379524; bh=LAMJhh3wHaVBSujHM3ID6UFUrjdB7S6pBQJKAWF5Tvw=; h=X-UI-Sender-Class:Date:From:To:Cc:Subject:References:In-Reply-To; b=kfL7kxOOsRzRSKueNT8YaK9mFHVg7WoJzI4AqweBeyZhCE6fE8JnMetccZgoDxMEB DLuLan+9O0izBrHqJy1OeLErN45XRBLOZBc1i1xsqLnTVpQ2Yo8E5LjE54QgqeRFJg 7dTIWYLqGKFs6bV0fUzdm6/ACn6Ios561pqSdpfA= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from E15-2016.optimum.net ([70.19.86.82]) by mail.gmx.net (mrgmx104 [212.227.17.174]) with ESMTPSA (Nemesis) id 1N6sn1-1lXZpE3IBb-018G4U; Sun, 25 Apr 2021 21:38:44 +0200 Date: Sun, 25 Apr 2021 15:38:41 -0400 From: Boruch Baum To: Drew Adams Subject: Re: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] Message-ID: <20210425193840.6dwy2mqwwb7s2etx@E15-2016.optimum.net> References: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="ypz63khbn3xjam7n" Content-Disposition: inline In-Reply-To: User-Agent: NeoMutt/20180716 X-Provags-ID: V03:K1:Kbg8daGg4pojw6e09tcM/ai+lSa963SeCYFjoljvuMSboPU7IlT 45GgjrnmT40MtFjwMOZl0/kmZ3PEuiIKaC2cw5arx1qA9dvTmc+35qsXZ5q88EcBisyrtQT Gxz/9MHn0L2G1jT1mv1vIYVX057JS3BSZneRB9I936zYuxD0ycvi2cFG0MTb7l1wJochvGs 9fyMyJhYacC6qYgqOHedg== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:zUNmOKmTRGs=:mq5jrK0xFK3lfVe/s3ouCY IlzjW60BcLnUhqKY1y/FQeL+qT3G9W7JjmXVD6GGlqp8D7otqnQZJ2NGjs+B0AtrqBKOr+TzB 3RsRknzjALOQaQP+5qiDEb+0aJj5A63T2C0BMjGvp07rgAoODkzBE06vjXZS3ywBfaOggG6a0 JvaeuTUOlH7S7vi6i7DhwX0u4ByZofOd46KsBXoRmard+GjbfWrH6BDbVq5Y4X8k1d1SDmdiq vWM63rHKhWNiFDAEuZ8n5fVllxV2kFP9PvCWnceu5bmkA4Azvk+p3IEE6Gt83Mnj13IGV2cO6 Vct8Tpgb3eQ6ACsT2rexnUDjqOUHblHfGEnp60DAQ3Rd3ArK7YUd7+joAUPJcukT3fh+/sfv2 eF1m2+92DtvvD6Sqf5EvhxfSI7fJsHg0S4867wiySJCpSLtSUgH8Ysxj2E3EdQ1uNMoHKSiIM 95D65B+5TjS74cHpIcI1wFqy9+D4vgkQBZI6/5IETe9mjBg/6OrsdwAhkHlgAStfr9iK1lNuK p8jIO8KB/qrfu6khk8ReWxtTUIP9buc81YVQRQRIRilK/DeUIJ7WIXh3MYoEb2j2UsCXM1ZR8 A5vlaFvdWuZqbLIn9fiT5lJMkkkToBujV99U57N/8waMXolL1CbquAf8BEt1mT57y344NDVab EvSznhPXM+HSecsq5D8sc8r5FPpHbQL4W3CAeZUkOWeu1Pa/Kcy2PAUOH8YG3CSbo1Ortj1BY yp148Zqu73mTlJAWu9RAVXTAyeGcoRGzGgM0AtxTAfFpZiIAwuOUSZ25oYTYUoTzGtVqYXy7M TFn/ANTAuBWKz20MO23qGLJDXTOXBQdOCgpWUVnu2U58HeGV2SOCIOkG3kQ27L2bPnuHsi3WD MlgY5ngLL3vfSVza1MGquIaASGM4W/3XaNpIRfy4FmtBB1Q0snCt5t3LY7Uat29jLPi8cHtn6 OrVV7s//v9Fuhx6IR/ojN6w9rg1k2OAy/gBBop78ggbw3XoJU51vQLeF10Nn2siOX57ACcSrX rE//gMzfuY86GfJl7Wff0UuGPmjC2o8gNrSbOZrN8f0uFMDH9TGK2Si4dBzQu55Fl3PHs7jEC 7GjOTLy1ZMswoTBbjVgWdViOGL6MLeRY0XKkzI5C5zKZKq1JxxHDBjdVWnJZk3+M7xafHEJ6n AOSuFnUBg08WSlL3Mt206yxk9g3bAWfKdxDCslVjC75gjeqUAesFNguBOZqXYE7X2VQNU= X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 47957 Cc: "47957@debbugs.gnu.org" <47957@debbugs.gnu.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) --ypz63khbn3xjam7n Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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. =2D- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 --ypz63khbn3xjam7n Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="dired-aux-3.patch" Content-Transfer-Encoding: quoted-printable diff --git a/dired-aux.el b/dired-aux.el index 3ee877e..1c10990 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)) @@ -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 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.) + "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=3D"" suppresses message. +Returns count of removed lines. FMT=3D\"\" 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")))))))) =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 +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-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 +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 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 +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 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 +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 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 +2034,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 +2044,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 +2060,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 +2071,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 +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-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 +2482,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 +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 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 +2600,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 +2613,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 +2649,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)) --ypz63khbn3xjam7n-- From debbugs-submit-bounces@debbugs.gnu.org Mon May 03 04:28:14 2021 Received: (at 47957) by debbugs.gnu.org; 3 May 2021 08:28:14 +0000 Received: from localhost ([127.0.0.1]:46143 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ldTw5-00035x-LW for submit@debbugs.gnu.org; Mon, 03 May 2021 04:28:13 -0400 Received: from quimby.gnus.org ([95.216.78.240]:39014) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ldTvz-00035I-11 for 47957@debbugs.gnu.org; Mon, 03 May 2021 04:28:12 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=8WcA/CC3BSmYyFJQfZACUGGDTDLy9m5YQZm703qRaHM=; b=T6HWPmrReBue0RSQtYi3w5vF9x +nbV2yiJMCBtmMYDBntmtVcmEa/9Ms1zoDXT2y0E/ua+NQ6uA74djgghwbEdRIUHjrUwyLvI/KcOY BEz5hi+DcE+fPYc3i30LEkJ+s18wSy+v/L/uak5Atq+nbE2UaijxfmOHV9xNh/QsP8Wc=; Received: from cm-84.212.220.105.getinternet.no ([84.212.220.105] helo=xo) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ldTvp-0002FD-Jd; Mon, 03 May 2021 10:27:59 +0200 From: Lars Ingebrigtsen To: Boruch Baum Subject: Re: bug#47957: dired-aux.el: convert comments to doctrings References: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> <83y2d6lqzo.fsf@gnu.org> <20210425091215.jctkznunn4re7su6@E15-2016.optimum.net> X-Now-Playing: The Style Council's _The Complete Adventures (1)_: "Long Hot Summer" Date: Mon, 03 May 2021 10:27:57 +0200 In-Reply-To: <20210425091215.jctkznunn4re7su6@E15-2016.optimum.net> (Boruch Baum's message of "Sun, 25 Apr 2021 05:12:15 -0400") Message-ID: <87mttcdxwy.fsf_-_@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Boruch Baum 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 someon [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 47957 Cc: Eli Zaretskii , drew.adams@oracle.com, 47957@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Boruch Baum 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 From debbugs-submit-bounces@debbugs.gnu.org Mon May 03 04:28:11 2021 Received: (at control) by debbugs.gnu.org; 3 May 2021 08:28:11 +0000 Received: from localhost ([127.0.0.1]:46141 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ldTw3-00035l-Fv for submit@debbugs.gnu.org; Mon, 03 May 2021 04:28:11 -0400 Received: from quimby.gnus.org ([95.216.78.240]:39030) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ldTw2-00035c-7V for control@debbugs.gnu.org; Mon, 03 May 2021 04:28:10 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Subject:From:To:Message-Id:Date:Sender:Reply-To:Cc: MIME-Version:Content-Type:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=dUBChcAlSGNT0zcdA4odXHmGOddfsImoi1J1eRS03+M=; b=Mq0panFeXwvQwIlqjUpK566ksy nZWZ7cop93/X71yDhDa71RDePiZlYCk7nqiV0MQML8FCjlQOtOIITel9ynFVmTXqVj+mKYSng+Lbi iRW4cH5Fr4yKBSZ3Ds4maFH/1SFsQWdUumukDNpy6DkJSfE2FObjkyS2Adlu7KuQFFYE=; Received: from cm-84.212.220.105.getinternet.no ([84.212.220.105] helo=xo) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ldTvv-0002FN-M1 for control@debbugs.gnu.org; Mon, 03 May 2021 10:28:04 +0200 Date: Mon, 03 May 2021 10:28:03 +0200 Message-Id: <87lf8wdxws.fsf@gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #47957 X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: tags 47957 wontfix close 47957 quit Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) tags 47957 wontfix close 47957 quit From unknown Sat Jun 21 10:40:11 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Mon, 31 May 2021 11:24:07 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator