From 6cf41850b3c422bcdc81c4ddbe2a88cf130b14e2 Mon Sep 17 00:00:00 2001
From: Adam Spiers <stow@adamspiers.org>
Date: Mon, 1 Apr 2024 16:34:01 +0100
Subject: [PATCH] foldable: rename $target => $target_subdir

The $target variable was ambiguous, as it could have referred to the
path to the target directory, or the path to a sub-directory in the
target, as well as its intended meaning of a subpath relative to the
target directory.  So rename it to try to find the balance between
clarity and verbosity.
---
 NEWS           |  2 +-
 lib/Stow.pm.in | 24 ++++++++++++------------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/NEWS b/NEWS
index 9d18951..6e27494 100644
--- a/NEWS
+++ b/NEWS
@@ -27,7 +27,7 @@ News file for Stow.
 ***** Improve readability of source code
 
       Quite a few extra details have been added in comments to clarify
-      how the code works.  Some variable names have also been
+      how the code works.  Many variable names have also been
       improved.  The comments of many Stow class methods have been
       converted into Perl POD format.
 
diff --git a/lib/Stow.pm.in b/lib/Stow.pm.in
index 2aa48a8..1e3fb05 100755
--- a/lib/Stow.pm.in
+++ b/lib/Stow.pm.in
@@ -1205,36 +1205,36 @@ sub cleanup_invalid_links {
 }
 
 
-=head2 foldable($target)
+=head2 foldable($target_subdir)
 
 Determine whether a tree can be folded
 
 =over 4
 
-=item $target
+=item $target_subdir
 
 path to a directory
 
 =back
 
 Returns path to the parent dir iff the tree can be safely folded.  The
-path returned is relative to the parent of $target, i.e. it can be
+path returned is relative to the parent of $target_subdir, i.e. it can be
 used as the source for a replacement symlink.
 
 =cut
 
 sub foldable {
     my $self = shift;
-    my ($target) = @_;
+    my ($target_subdir) = @_;
 
-    debug(3, 2, "Is $target foldable?");
+    debug(3, 2, "Is $target_subdir foldable?");
     if ($self->{'no-folding'}) {
         debug(3, 3, "no because --no-folding enabled");
         return '';
     }
 
-    opendir my $DIR, $target
-        or error(qq{Cannot read directory "$target" ($!)\n});
+    opendir my $DIR, $target_subdir
+        or error(qq{Cannot read directory "$target_subdir" ($!)\n});
     my @listing = readdir $DIR;
     closedir $DIR;
 
@@ -1245,7 +1245,7 @@ sub foldable {
         next NODE if $node eq '.';
         next NODE if $node eq '..';
 
-        my $path =  join_paths($target, $node);
+        my $path =  join_paths($target_subdir, $node);
 
         # Skip nodes scheduled for removal
         next NODE if not $self->is_a_node($path);
@@ -1267,16 +1267,16 @@ sub foldable {
     }
     return '' if not $parent;
 
-    # If we get here then all nodes inside $target are links, and those links
+    # If we get here then all nodes inside $target_subdir are links, and those links
     # point to nodes inside the same directory.
 
     # chop of leading '..' to get the path to the common parent directory
-    # relative to the parent of our $target
+    # relative to the parent of our $target_subdir
     $parent =~ s{\A\.\./}{};
 
     # If the resulting path is owned by stow, we can fold it
-    if ($self->link_owned_by_package($target, $parent)) {
-        debug(3, 3, "$target is foldable");
+    if ($self->link_owned_by_package($target_subdir, $parent)) {
+        debug(3, 3, "$target_subdir is foldable");
         return $parent;
     }
     else {