From 9db0de3005d49d27e0a31e5d6bc9655a78444165 Mon Sep 17 00:00:00 2001
From: Adam Spiers <stow@adamspiers.org>
Date: Sat, 9 Mar 2024 18:11:00 +0000
Subject: [PATCH] Add some helpful comments

Explain a few things in preparation for a bugfix.
---
 lib/Stow.pm.in       | 11 +++++++++--
 t/find_stowed_path.t |  3 +++
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/lib/Stow.pm.in b/lib/Stow.pm.in
index 313cb83..9413f8f 100755
--- a/lib/Stow.pm.in
+++ b/lib/Stow.pm.in
@@ -202,6 +202,11 @@ sub set_stow_dir {
 
     my $stow_dir = canon_path($self->{dir});
     my $target = canon_path($self->{target});
+
+    # Calculate relative path from target directory to stow directory.
+    # This will be commonly used as a prefix for constructing and
+    # recognising symlinks "installed" in the target directory which
+    # point to package files under the stow directory.
     $self->{stow_path} = File::Spec->abs2rel($stow_dir, $target);
 
     debug(2, 0, "stow dir is $stow_dir");
@@ -925,8 +930,10 @@ sub link_owned_by_package {
 
 #===== METHOD ===============================================================
 # Name      : find_stowed_path()
-# Purpose   : determine whether the given link points to a member of a
-#           : stowed package
+# Purpose   : determine whether the given link within the target directory
+#           : is a stowed path pointing to a member of a package under the
+#           : stow dir, and if so, obtain a breakdown of information about
+#           : this stowed path.
 # Parameters: $target => path to a symbolic link under current directory.
 #           :            Must share a common prefix with $self->{stow_path}
 #           : $source => where that link points to (needed because link
diff --git a/t/find_stowed_path.t b/t/find_stowed_path.t
index 7b82520..4a61427 100755
--- a/t/find_stowed_path.t
+++ b/t/find_stowed_path.t
@@ -62,6 +62,9 @@ is($path, "", "empty path");
 is($stow_path, "", "empty stow path");
 is($package, "", "target is not stowed");
 
+# Make a second stow directory within the target directory, so that we
+# can check that links to package files within that second stow
+# directory are detected correctly.
 make_path("$TEST_DIR/target/stow2");
 make_file("$TEST_DIR/target/stow2/.stow");