00dani/stow
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Improve comments on function parameters for clarity

Browse source
This commit is contained in:
Adam Spiers 2019-06-28 15:22:29 +01:00
parent e4f6a6742b
commit 3270b145e1
1 changed files with 13 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
lib/Stow.pm.in
View file

@ -354,7 +354,9 @@ sub within_target_do {
# Parameters: $stow_path => relative path from current (i.e. target) directory # Parameters: $stow_path => relative path from current (i.e. target) directory
# : to the stow dir containing the package to be stowed # : to the stow dir containing the package to be stowed
# : $package => the package whose contents are being stowed # : $package => the package whose contents are being stowed
# : $target => subpath relative to package and target directories # : $target => subpath relative to package directory which needs
# : stowing as a symlink at subpath relative to target
# : directory.
# : $source => relative path from the (sub)dir of target # : $source => relative path from the (sub)dir of target
# : to symlink source # : to symlink source
# Returns : n/a # Returns : n/a
@ -415,7 +417,9 @@ sub stow_contents {
# Parameters: $stow_path => relative path from current (i.e. target) directory # Parameters: $stow_path => relative path from current (i.e. target) directory
# : to the stow dir containing the node to be stowed # : to the stow dir containing the node to be stowed
# : $package => the package containing the node being stowed # : $package => the package containing the node being stowed
# : $target => subpath relative to package and target directories # : $target => subpath relative to package directory of node which
# : needs stowing as a symlink at subpath relative to
# : target directory.
# : $source => relative path to symlink source from the dir of target # : $source => relative path to symlink source from the dir of target
# Returns : n/a # Returns : n/a
# Throws : fatal exception if a conflict arises # Throws : fatal exception if a conflict arises
@ -912,18 +916,20 @@ sub path_owned_by_package {
# Name : find_stowed_path() # Name : find_stowed_path()
# Purpose : determine whether the given link points to a member of a # Purpose : determine whether the given link points to a member of a
# : stowed package # : stowed package
# Parameters: $target => path to a symbolic link under current directory # 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 # : $source => where that link points to (needed because link
# : might not exist yet due to two-phase approach, # : might not exist yet due to two-phase approach,
# : so we can't just call readlink()) # : so we can't just call readlink()). This must be
# : expressed relative to (the directory containing)
# : $target.
# Returns : ($path, $stow_path, $package) where $path and $stow_path are # Returns : ($path, $stow_path, $package) where $path and $stow_path are
# : relative from the current (i.e. target) directory. $path # : relative from the current (i.e. target) directory. $path
# : is the full relative path, $stow_path is the relative path # : is the full relative path, $stow_path is the relative path
# : to the stow directory, and $package is the name of the package. # : to the stow directory, and $package is the name of the package.
# : or ('', '', '') if link is not owned by stow # : or ('', '', '') if link is not owned by stow
# Throws : n/a # Throws : n/a
# Comments : Needs # Comments : Allow for stow dir not being under target dir.
# : Allow for stow dir not being under target dir.
# : We could put more logic under here for multiple stow dirs. # : We could put more logic under here for multiple stow dirs.
#============================================================================ #============================================================================
sub find_stowed_path { sub find_stowed_path {
@ -971,7 +977,7 @@ sub find_stowed_path {
} }
my $package = shift @path; my $package = shift @path;
debug(4, " yes - by $package in " . join_paths(@path)); debug(4, " yes - by $package in " . join_paths(@path));
return ($path, $self->{stow_path}, $package); return ($path, $self->{stow_path}, $package);
} }