Stow.pm: reformat comments
Some methods had comments with a prefix which made the paragraph inconveniently narrow, and made refilling it really awkward. So switch to a more natural comment style.
This commit is contained in:
Adam Spiers
parent
11d4ff01d7
commit
1be40c0532
138
lib/Stow.pm.in
138
lib/Stow.pm.in
|
|
@ -340,9 +340,10 @@ sub plan_stow {
|
|||
# Parameters: $code => anonymous subroutine to execute within target dir
|
||||
# Returns : n/a
|
||||
# Throws : n/a
|
||||
# Comments : This is done to ensure that the consumer of the Stow interface
|
||||
# : doesn't have to worry about (a) what their cwd is, and
|
||||
# : (b) that their cwd might change.
|
||||
#
|
||||
# This is done to ensure that the consumer of the Stow interface
|
||||
# doesn't have to worry about (a) what their cwd is, and (b) that
|
||||
# their cwd might change.
|
||||
# ============================================================================
|
||||
sub within_target_do {
|
||||
my $self = shift;
|
||||
|
|
@ -376,9 +377,10 @@ sub within_target_do {
|
|||
# : to symlink source
|
||||
# Returns : n/a
|
||||
# Throws : a fatal error if directory cannot be read
|
||||
# Comments : stow_node() and stow_contents() are mutually recursive.
|
||||
# : $source and $target are used for creating the symlink
|
||||
# : $path is used for folding/unfolding trees as necessary
|
||||
#
|
||||
# stow_node() and stow_contents() are mutually recursive. $source and
|
||||
# $target are used for creating the symlink $path is used for
|
||||
# folding/unfolding trees as necessary
|
||||
# ============================================================================
|
||||
sub stow_contents {
|
||||
my $self = shift;
|
||||
|
|
@ -447,9 +449,10 @@ sub stow_contents {
|
|||
# : $source => relative path to symlink source from the dir of target
|
||||
# Returns : n/a
|
||||
# Throws : fatal exception if a conflict arises
|
||||
# Comments : stow_node() and stow_contents() are mutually recursive.
|
||||
# : $source and $target are used for creating the symlink
|
||||
# : $path is used for folding/unfolding trees as necessary
|
||||
#
|
||||
# stow_node() and stow_contents() are mutually recursive. $source and
|
||||
# $target are used for creating the symlink $path is used for
|
||||
# folding/unfolding trees as necessary
|
||||
# ============================================================================
|
||||
sub stow_node {
|
||||
my $self = shift;
|
||||
|
|
@ -593,8 +596,9 @@ sub stow_node {
|
|||
# Parameters: $target => relative path to symlink target from the current directory
|
||||
# Returns : true iff target is a stow directory
|
||||
# Throws : n/a
|
||||
# Comments : cwd must be the top-level target directory, otherwise
|
||||
# : marked_stow_dir() won't work.
|
||||
#
|
||||
# cwd must be the top-level target directory, otherwise
|
||||
# marked_stow_dir() won't work.
|
||||
# ============================================================================
|
||||
sub should_skip_target {
|
||||
my $self = shift;
|
||||
|
|
@ -639,8 +643,9 @@ sub marked_stow_dir {
|
|||
# : $target => relative path to symlink target from the current directory
|
||||
# Returns : n/a
|
||||
# Throws : a fatal error if directory cannot be read
|
||||
# Comments : unstow_node_orig() and unstow_contents_orig() are mutually recursive
|
||||
# : Here we traverse the target tree, rather than the source tree.
|
||||
#
|
||||
# unstow_node_orig() and unstow_contents_orig() are mutually recursive.
|
||||
# Here we traverse the target tree, rather than the source tree.
|
||||
# ============================================================================
|
||||
sub unstow_contents_orig {
|
||||
my $self = shift;
|
||||
|
|
@ -683,7 +688,8 @@ sub unstow_contents_orig {
|
|||
# : $target => relative path to symlink target from the current directory
|
||||
# Returns : n/a
|
||||
# Throws : fatal error if a conflict arises
|
||||
# Comments : unstow_node() and unstow_contents() are mutually recursive
|
||||
#
|
||||
# unstow_node() and unstow_contents() are mutually recursive.
|
||||
# ============================================================================
|
||||
sub unstow_node_orig {
|
||||
my $self = shift;
|
||||
|
|
@ -759,8 +765,9 @@ sub unstow_node_orig {
|
|||
# : $target => relative path to symlink target from the current directory
|
||||
# Returns : n/a
|
||||
# Throws : a fatal error if directory cannot be read
|
||||
# Comments : unstow_node() and unstow_contents() are mutually recursive
|
||||
# : Here we traverse the source tree, rather than the target tree.
|
||||
#
|
||||
# unstow_node() and unstow_contents() are mutually recursive.
|
||||
# Here we traverse the source tree, rather than the target tree.
|
||||
# ============================================================================
|
||||
sub unstow_contents {
|
||||
my $self = shift;
|
||||
|
|
@ -816,7 +823,8 @@ sub unstow_contents {
|
|||
# : $target => relative path to symlink target from the current directory
|
||||
# Returns : n/a
|
||||
# Throws : fatal error if a conflict arises
|
||||
# Comments : unstow_node() and unstow_contents() are mutually recursive
|
||||
#
|
||||
# unstow_node() and unstow_contents() are mutually recursive.
|
||||
# ============================================================================
|
||||
sub unstow_node {
|
||||
my $self = shift;
|
||||
|
|
@ -923,7 +931,8 @@ sub unstow_node {
|
|||
# : $source => where that link points to
|
||||
# Returns : the package iff link is owned by stow, otherwise ''
|
||||
# Throws : n/a
|
||||
# Comments : lossy wrapper around find_stowed_path()
|
||||
#
|
||||
# lossy wrapper around find_stowed_path().
|
||||
# ============================================================================
|
||||
sub link_owned_by_package {
|
||||
my $self = shift;
|
||||
|
|
@ -959,9 +968,10 @@ sub link_owned_by_package {
|
|||
# : to the stow directory; and $package is the name of the
|
||||
# : package; or ('', '', '') if link is not owned by stow.
|
||||
# Throws : n/a
|
||||
# Comments : cwd must be the top-level target directory, otherwise
|
||||
# : find_containing_marked_stow_dir() won't work.
|
||||
# : Allow for stow dir not being under target dir.
|
||||
#
|
||||
# cwd must be the top-level target directory, otherwise
|
||||
# find_containing_marked_stow_dir() won't work. Allow for stow dir
|
||||
# not being under target dir.
|
||||
# ============================================================================
|
||||
sub find_stowed_path {
|
||||
my $self = shift;
|
||||
|
|
@ -1034,8 +1044,9 @@ sub link_dest_within_stow_dir {
|
|||
# : as a Stow directory, and $package is the containing package;
|
||||
# : or ('', '') if no containing directory is marked as a stow
|
||||
# : directory.
|
||||
# Comments : cwd must be the top-level target directory, otherwise
|
||||
# : marked_stow_dir() won't work.
|
||||
#
|
||||
# cwd must be the top-level target directory, otherwise
|
||||
# marked_stow_dir() won't work.
|
||||
# =============================================================================
|
||||
sub find_containing_marked_stow_dir {
|
||||
my $self = shift;
|
||||
|
|
@ -1067,13 +1078,14 @@ sub find_containing_marked_stow_dir {
|
|||
# Parameters: $dir => path to directory to check
|
||||
# Returns : n/a
|
||||
# Throws : no exceptions
|
||||
# Comments : This is invoked by unstow_contents().
|
||||
# : We only clean up links which are both orphaned and owned by
|
||||
# : Stow, i.e. they point to a non-existent location within a
|
||||
# : Stow package. These can block tree folding, and they can
|
||||
# : easily occur when a file in Stow package is renamed or removed,
|
||||
# : so the benefit should outweigh the low risk of actually someone
|
||||
# : wanting to keep an orphaned link to within a Stow package.
|
||||
#
|
||||
# This is invoked by unstow_contents(). We only clean up links which
|
||||
# are both orphaned and owned by Stow, i.e. they point to a
|
||||
# non-existent location within a Stow package. These can block tree
|
||||
# folding, and they can easily occur when a file in Stow package is
|
||||
# renamed or removed, so the benefit should outweigh the low risk of
|
||||
# actually someone wanting to keep an orphaned link to within a Stow
|
||||
# package.
|
||||
# =============================================================================
|
||||
sub cleanup_invalid_links {
|
||||
my $self = shift;
|
||||
|
|
@ -1152,8 +1164,9 @@ sub cleanup_invalid_links {
|
|||
# Parameters: $target => path to a directory
|
||||
# Returns : path to the parent dir iff the tree can be safely folded
|
||||
# Throws : n/a
|
||||
# Comments : the path returned is relative to the parent of $target,
|
||||
# : that is, it can be used as the source for a replacement symlink
|
||||
#
|
||||
# The path returned is relative to the parent of $target, i.e. it can
|
||||
# be used as the source for a replacement symlink.
|
||||
# ============================================================================
|
||||
sub foldable {
|
||||
my $self = shift;
|
||||
|
|
@ -1223,7 +1236,8 @@ sub foldable {
|
|||
# : $target => directory that we will replace with a link to $source
|
||||
# Returns : n/a
|
||||
# Throws : none
|
||||
# Comments : only called iff foldable() is true so we can remove some checks
|
||||
#
|
||||
# Only called iff foldable() is true so we can remove some checks.
|
||||
# ============================================================================
|
||||
sub fold_tree {
|
||||
my $self = shift;
|
||||
|
|
@ -1256,7 +1270,6 @@ sub fold_tree {
|
|||
# : $message => a description of the conflict
|
||||
# Returns : n/a
|
||||
# Throws : none
|
||||
# Comments : none
|
||||
# ============================================================================
|
||||
sub conflict {
|
||||
my $self = shift;
|
||||
|
|
@ -1335,7 +1348,6 @@ sub get_action_count {
|
|||
# : relative to its package directory
|
||||
# Returns : true iff the path should be ignored
|
||||
# Throws : no exceptions
|
||||
# Comments : none
|
||||
# =============================================================================
|
||||
sub ignore {
|
||||
my $self = shift;
|
||||
|
|
@ -1518,7 +1530,6 @@ sub get_default_global_ignore_regexps {
|
|||
# Parameters: $path
|
||||
# Returns : Boolean
|
||||
# Throws : no exceptions
|
||||
# Comments : none
|
||||
# =============================================================================
|
||||
sub defer {
|
||||
my $self = shift;
|
||||
|
|
@ -1536,7 +1547,6 @@ sub defer {
|
|||
# Parameters: $path
|
||||
# Returns : Boolean
|
||||
# Throws : no exceptions
|
||||
# Comments : none
|
||||
# =============================================================================
|
||||
sub override {
|
||||
my $self = shift;
|
||||
|
|
@ -1561,7 +1571,6 @@ sub override {
|
|||
# Parameters: none
|
||||
# Returns : n/a
|
||||
# Throws : fatal error if tasks list is corrupted or a task fails
|
||||
# Comments : none
|
||||
# ============================================================================
|
||||
sub process_tasks {
|
||||
my $self = shift;
|
||||
|
|
@ -1590,9 +1599,10 @@ sub process_tasks {
|
|||
# Parameters: $task => the task to process
|
||||
# Returns : n/a
|
||||
# Throws : fatal error if task fails
|
||||
# Comments : Must run from within target directory.
|
||||
# : Task involve either creating or deleting dirs and symlinks
|
||||
# : an action is set to 'skip' if it is found to be redundant
|
||||
#
|
||||
# Must run from within target directory. Task involve either creating
|
||||
# or deleting dirs and symlinks an action is set to 'skip' if it is
|
||||
# found to be redundant
|
||||
# ============================================================================
|
||||
sub process_task {
|
||||
my $self = shift;
|
||||
|
|
@ -1646,7 +1656,6 @@ sub process_task {
|
|||
# Parameters: $path
|
||||
# Returns : 'remove', 'create', or '' if there is no action
|
||||
# Throws : a fatal exception if an invalid action is found
|
||||
# Comments : none
|
||||
# ============================================================================
|
||||
sub link_task_action {
|
||||
my $self = shift;
|
||||
|
|
@ -1671,7 +1680,6 @@ sub link_task_action {
|
|||
# Parameters: $path
|
||||
# Returns : 'remove', 'create', or '' if there is no action
|
||||
# Throws : a fatal exception if an invalid action is found
|
||||
# Comments : none
|
||||
# ============================================================================
|
||||
sub dir_task_action {
|
||||
my $self = shift;
|
||||
|
|
@ -1697,7 +1705,6 @@ sub dir_task_action {
|
|||
# Parameters: $path
|
||||
# Returns : Boolean
|
||||
# Throws : none
|
||||
# Comments : none
|
||||
# ============================================================================
|
||||
sub parent_link_scheduled_for_removal {
|
||||
my $self = shift;
|
||||
|
|
@ -1724,8 +1731,9 @@ sub parent_link_scheduled_for_removal {
|
|||
# Parameters: $path
|
||||
# Returns : Boolean
|
||||
# Throws : none
|
||||
# Comments : returns false if an existing link is scheduled for removal
|
||||
# : and true if a non-existent link is scheduled for creation
|
||||
#
|
||||
# Returns false if an existing link is scheduled for removal and true
|
||||
# if a non-existent link is scheduled for creation.
|
||||
# ============================================================================
|
||||
sub is_a_link {
|
||||
my $self = shift;
|
||||
|
|
@ -1760,9 +1768,10 @@ sub is_a_link {
|
|||
# Parameters: $path
|
||||
# Returns : Boolean
|
||||
# Throws : none
|
||||
# Comments : returns false if an existing directory is scheduled for removal
|
||||
# : and true if a non-existent directory is scheduled for creation
|
||||
# : we also need to be sure we are not just following a link
|
||||
#
|
||||
# Returns false if an existing directory is scheduled for removal and
|
||||
# true if a non-existent directory is scheduled for creation. We also
|
||||
# need to be sure we are not just following a link.
|
||||
# ============================================================================
|
||||
sub is_a_dir {
|
||||
my $self = shift;
|
||||
|
|
@ -1795,9 +1804,10 @@ sub is_a_dir {
|
|||
# Parameters: $path
|
||||
# Returns : Boolean
|
||||
# Throws : none
|
||||
# Comments : returns false if an existing node is scheduled for removal
|
||||
# : true if a non-existent node is scheduled for creation
|
||||
# : we also need to be sure we are not just following a link
|
||||
#
|
||||
# Returns false if an existing node is scheduled for removal true if a
|
||||
# non-existent node is scheduled for creation. we also need to be
|
||||
# sure we are not just following a link.
|
||||
# ============================================================================
|
||||
sub is_a_node {
|
||||
my $self = shift;
|
||||
|
|
@ -1868,7 +1878,6 @@ sub is_a_node {
|
|||
# Returns : a string
|
||||
# Throws : fatal exception if the given path is not a current or planned
|
||||
# : link
|
||||
# Comments : none
|
||||
# ============================================================================
|
||||
sub read_a_link {
|
||||
my $self = shift;
|
||||
|
|
@ -1901,7 +1910,8 @@ sub read_a_link {
|
|||
# : $newfile => the file to link
|
||||
# Returns : n/a
|
||||
# Throws : error if this clashes with an existing planned operation
|
||||
# Comments : cleans up operations that undo previous operations
|
||||
#
|
||||
# Cleans up operations that undo previous operations.
|
||||
# ============================================================================
|
||||
sub do_link {
|
||||
my $self = shift;
|
||||
|
|
@ -1978,7 +1988,8 @@ sub do_link {
|
|||
# Parameters: $file => the file to unlink
|
||||
# Returns : n/a
|
||||
# Throws : error if this clashes with an existing planned operation
|
||||
# Comments : will remove an existing planned link
|
||||
#
|
||||
# Will remove an existing planned link.
|
||||
# ============================================================================
|
||||
sub do_unlink {
|
||||
my $self = shift;
|
||||
|
|
@ -2033,9 +2044,11 @@ sub do_unlink {
|
|||
# Parameters: $dir => the directory to remove
|
||||
# Returns : n/a
|
||||
# Throws : fatal exception if operation fails
|
||||
# Comments : outputs a message if 'verbose' option is set
|
||||
# : does not perform operation if 'simulate' option is set
|
||||
# Comments : cleans up operations that undo previous operations
|
||||
#
|
||||
# Outputs a message if 'verbose' option is set.
|
||||
# Does not perform operation if 'simulate' option is set.
|
||||
#
|
||||
# Cleans up operations that undo previous operations.
|
||||
# ============================================================================
|
||||
sub do_mkdir {
|
||||
my $self = shift;
|
||||
|
|
@ -2096,8 +2109,9 @@ sub do_mkdir {
|
|||
# Parameters: $dir => the directory to remove
|
||||
# Returns : n/a
|
||||
# Throws : fatal exception if operation fails
|
||||
# Comments : outputs a message if 'verbose' option is set
|
||||
# : does not perform operation if 'simulate' option is set
|
||||
#
|
||||
# Outputs a message if 'verbose' option is set.
|
||||
# Does not perform operation if 'simulate' option is set.
|
||||
# ============================================================================
|
||||
sub do_rmdir {
|
||||
my $self = shift;
|
||||
|
|
@ -2151,7 +2165,8 @@ sub do_rmdir {
|
|||
# : $dst => the path to move it to
|
||||
# Returns : n/a
|
||||
# Throws : error if this clashes with an existing planned operation
|
||||
# Comments : alters contents of package installation image in stow dir
|
||||
#
|
||||
# Alters contents of package installation image in stow dir.
|
||||
# ============================================================================
|
||||
sub do_mv {
|
||||
my $self = shift;
|
||||
|
|
@ -2204,7 +2219,6 @@ sub do_mv {
|
|||
# Parameters: $message => error message to output
|
||||
# Returns : n/a
|
||||
# Throws : n/a
|
||||
# Comments : none
|
||||
# ============================================================================
|
||||
sub internal_error {
|
||||
my ($format, @args) = @_;
|
||||
|
|
|
|||
Loading…
Reference in a new issue