From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#47957: [External] : bug#47957: diredx-aux doctrings [PATCH INCLUDED] Date: Sun, 25 Apr 2021 11:15:23 +0300 Message-ID: <83y2d6lqzo.fsf@gnu.org> References: <20210422194508.mbsunzjovwdpyp2i@E15-2016.optimum.net> <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="27012"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 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 10:16:10 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 1laZw2-0006vZ-Ow for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 25 Apr 2021 10:16:10 +0200 Original-Received: from localhost ([::1]:53450 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1laZw1-00061Y-S1 for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 25 Apr 2021 04:16:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38630) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1laZvu-00061E-GK for bug-gnu-emacs@gnu.org; Sun, 25 Apr 2021 04:16:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:58628) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1laZvu-0000dY-5c for bug-gnu-emacs@gnu.org; Sun, 25 Apr 2021 04:16:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1laZvu-0000uI-1r for bug-gnu-emacs@gnu.org; Sun, 25 Apr 2021 04:16:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 25 Apr 2021 08:16:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 47957 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 47957-submit@debbugs.gnu.org id=B47957.16193385523472 (code B ref 47957); Sun, 25 Apr 2021 08:16:02 +0000 Original-Received: (at 47957) by debbugs.gnu.org; 25 Apr 2021 08:15:52 +0000 Original-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 Original-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 Original-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 Original-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 In-Reply-To: <20210425052212.ao4ugrbsbloxnkon@E15-2016.optimum.net> (message from Boruch Baum on Sun, 25 Apr 2021 01:22:12 -0400) 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:204849 Archived-At: > 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.