Hi there, Thanks for taking a look.

Apologies for the sloppiness you pointed out, this was originally targeted
for the MELPA, but I was advised that this could be useful functionality in
mainline, so this is my first time attempting to contribute directly to
emacs :)

> Why do you call this a "ring"?  AFAICT, it is a simple list, created
> and used as such.

To be perfectly honest, it was just the first thing that came to mind to
help distinguish this feature. If anybody has any better suggestions I can
append accordingly.

> Why does this use 'concat' instead of 'expand-file-name'?
The (file-name-nondirectory (directory-file-name file)) in the snippet
returns a bare filename. I use concat here to set the destination as an
identical filename, in the default-directory.

> What happens with files in subdirectories, e.g., if the user typed 'i'
> before marking files?  Does this command create the corresponding
> subdirectories in the default-directory when it moves the files?
Yes, the files have their actions performed recursively, so all subdirs are
created as well.

I have noticed just now though, in your example, default-directory remains
unchanged, but it looks like if I swap to (dired-current-directory)
instead, it should be resolved properly when in a subdir. Thanks for
catching that.

I'll also work on amending all the documentation mistakes you pointed out
as well.

> This feature, when installed, will need a NEWS entry.
I might just not be looking hard enough, but do you have any resources
available that I could look into for this? :)

> Finally, to accept a contribution of this size we need you to sign the
> copyright assignment agreement.  Would you like to start this legal
> paperwork rolling at this time?  If yes, I will send you the form to
> fill and the instructions to go with it.

Of course! Very much appreciated.

On Mon, Oct 21, 2024 at 4:48 AM Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Justin Fields <justinlime1999@gmail.com>
> > Date: Mon, 21 Oct 2024 03:11:23 -0500
> >
> > From ca8f28008aeb95e74a0b5de28445cc25602ab724 Mon Sep 17 00:00:00 2001
> > From: Justin Fields <justinlime1999@gmail.com>
> > Date: Sun, 20 Oct 2024 22:54:57 -0500
> > Subject: [PATCH] Dired-Aux: add file ring to dired
>
> Thanks.  Some comments below.  If someone else has comments, please
> post them.
>
> > +;;; File ring
> > +(defvar dired-file-ring nil
> > +  "Captured dired files.")
>
> Why do you call this a "ring"?  AFAICT, it is a simple list, created
> and used as such.
>
> > +(defun dired-file-ring-execute (action action-name file-list)
> > +  "Execute a function to run for every item in the FILE-LIST.
>
> The first line of a doc string should preferably mention all of the
> mandatory arguments.
>
> > +Argument ACTION argument to call with `dired-create-files' with as
> > +its' FILE-CREATOR.
>
> This reads awkwardly due to lack of punctuation.  Our usual style is
> to say
>
>   ACTION is passed to `dired-create-files' as its FILE-CREATOR
>   argument.
>
> Same comment for the other arguments.
>
> > +Argument ACTION-NAME The name of the action, used for logging.
>
> This should say "...for error logging by `dired-create-files'.", so
> that readers could look up that logging.
>
> > +  (dired-create-files action action-name file-list
> > +    (lambda (file) (concat default-directory (file-name-nondirectory
> (directory-file-name file)))))
>
> Why does this use 'concat' instead of 'expand-file-name'?
>
> > +(defun dired-file-ring-capture ()
> > +  "Capture marked Dired files to the file ring."
> > +  (interactive)
> > +  (mapc (lambda (file) (add-to-list 'dired-file-ring file))
> (dired-get-marked-files))
> > +  (message "Captured %s Files. %s files are present in the file ring"
> (length (dired-get-marked-files)) (length dired-file-ring)))
>
> This will say "Captured 1 Files", which is incorrect English.  Please
> use ngettext to do this better.
>
> My suggestion is to rephrase this message to say something like
>
>   %s files now in `file-ring', %s added
>
> This makes the message much shorter and easier to understand, IMO.
>
> > +(defun dired-file-ring-move ()
> > +  "Move the file/s from the file ring to current dir.
>
> By "current dir" do you mean default-directory?  We don't use the term
> "current directory" in Emacs because Emacs pretends that each buffer
> has its own "current directory".
>
> > +This action clears the file ring."
> > +  (interactive)
> > +  (dired-file-ring-execute #'rename-file "MOVE" dired-file-ring)
> > +  (dired-file-ring-clear))
>
> What happens with files in subdirectories, e.g., if the user typed 'i'
> before marking files?  Does this command create the corresponding
> subdirectories in the default-directory when it moves the files?
>
> > +(defun dired-file-ring-copy ()
> > +  "Copy the file/s from the file ring to current dir."
> > +  (interactive)
> > +  (dired-file-ring-execute #'dired-copy-file "COPY" dired-file-ring))
>
> Same question here.
>
> > +(defun dired-file-ring-symlink ()
> > +  "Create a symlink for the the file/s from the file ring to current
> dir."
> > +  (interactive)
> > +  (dired-file-ring-execute #'make-symbolic-link "SYM-LINK"
> dired-file-ring))
> > +
> > +(defun dired-file-ring-symlink-relative ()
> > +  "Create a relative symlink for the the file/s from the file ring to
> current dir."
> > +  (interactive)
> > +  (dired-file-ring-execute #'dired-make-relative-symlink "RELATIVE
> SYM-LINK" dired-file-ring))
>
> The doc strings of these two commands should be more explicit
> regarding which file is the symlink and what will be its target.
>
> This feature, when installed, will need a NEWS entry.
>
> Finally, to accept a contribution of this size we need you to sign the
> copyright assignment agreement.  Would you like to start this legal
> paperwork rolling at this time?  If yes, I will send you the form to
> fill and the instructions to go with it.
>