From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] Date: Sun, 25 Apr 2021 18:21:04 +0000 Message-ID: References: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="24724"; mail-complaints-to="usenet@ciao.gmane.io" Cc: "47957@debbugs.gnu.org" <47957@debbugs.gnu.org> To: Boruch Baum Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Apr 25 20:22:37 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lajOu-0006KC-S3 for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 25 Apr 2021 20:22:37 +0200 Original-Received: from localhost ([::1]:39310 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lajOs-0001Rs-4G for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 25 Apr 2021 14:22:35 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:49638) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lajOM-0001R6-RB for bug-gnu-emacs@gnu.org; Sun, 25 Apr 2021 14:22:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60431) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lajOM-0002OU-Aw for bug-gnu-emacs@gnu.org; Sun, 25 Apr 2021 14:22:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1lajOM-0003eW-7R for bug-gnu-emacs@gnu.org; Sun, 25 Apr 2021 14:22:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 25 Apr 2021 18:22:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 47957 X-GNU-PR-Package: emacs Original-Received: via spool by 47957-submit@debbugs.gnu.org id=B47957.161937487813967 (code B ref 47957); Sun, 25 Apr 2021 18:22:02 +0000 Original-Received: (at 47957) by debbugs.gnu.org; 25 Apr 2021 18:21:18 +0000 Original-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 Original-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 Original-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== Original-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 Original-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 Original-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= Original-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 Original-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 Thread-Topic: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] Thread-Index: AQHXOZL54roEzmPrbEulSkapgJ2a16rFbQdQ In-Reply-To: <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> Accept-Language: en-US Content-Language: en-US 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: e/yvuPNe710cNd9dytjQMNyKkBzghCpI6KWFGEiID+wGBfcHMkp07hMROFpRB0TQ+NXBygc/XLSMPyT7o139tB4HqpnxihecgFdsQBHdwLbP5vdjP0JU1kqkLzeQTEVWHl39Klwsmada5vkyYQdkkMyMKNgt6mNEd5F5OBhkbLBQwq+zwxswQILcUHe8zaurLUD/zvlC4eaSKLgb7P5pBSVWXKE1aJSI1L3wxd3VrOecsotzb0pY0wNKIQlFtNNrP+JQcn3D/WC0MmvE2OtAGmAoAz+0PzD5A9DZj7d+J4t1hriopd0FKARa8WZiVraKa9uMc7+a3iOsVF3lngrobTtfFSeY20BGykfWm01F63LzhA6ebCmudwe93r/C29crZsdoL2pku/0T5jfBib2SjGfuJu8qAjDzuEJlNTItJ6F+5v+4la58n96w8DUQLovQh8K43zTxod2IlKxgmOFcQ6O/gg5OLS8N+427e4rU+jyfAh6EaF+q/LA1jmAbvSmYC3QRSkm7jw8b7HzJn9pKrt8pllb4zkihPrgtwJlD8zZbBZRXhk0BrCtNtjXHpYo5zCLrZdHBDwM2OCUQ8qKR+gxj/IS5hg6dnhzDmrbrE2bXhDOixlM/WAps2kcw2RXlMJOb0402iQYK/xOZrw9U6w/zAKvtLx4o9OJgI2TkkkZAU0rzfgpsQo2VtLqs573XHIY9Szu6On6fACW/TwRVjNxZCVGOXP4ZxJ1RV9XjfzxYrNcEw+eNDAiVh6Vk 7gwv+pXJB7Ue64c2Aw9kX49JbJKVRKTsBCFlC2sZNRJrnYLRQ7myguPZXzhYowzTrbGrVw63gVu5kTWCP5N+/LffI0QMzZI/1b x-ms-exchange-transport-forked: True 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:204900 Archived-At: > > 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.