hold targeter reify experiment

Signed-off-by: Bill Erickson <berickxx@gmail.com>

diff --git a/Open-ILS/src/perlmods/lib/OpenILS/Utils/HoldTargeter.pm b/Open-ILS/src/perlmods/lib/OpenILS/Utils/HoldTargeter.pm
index 6cd8be5..4a29a07 100644 (file)
--- a/Open-ILS/src/perlmods/lib/OpenILS/Utils/HoldTargeter.pm
+++ b/Open-ILS/src/perlmods/lib/OpenILS/Utils/HoldTargeter.pm
@@ -654,20 +654,23 @@ sub inspect_previous_target {
     return 1;
 }
 
-# Returns true if we have at least one potential copy, thus targeting 
-# should continue.  Otherwise, the hold is updated to reflect that 
-# there is no target and returns false, to stop targeting.
+# Returns true if we have at least one potential copy remaining, thus 
+# targeting should continue.  Otherwise, the hold is updated to reflect 
+# that there is no target and returns false to stop targeting.
 sub handle_no_copies {
     my ($self, %args) = @_;
 
     if (!$args{force}) {
-        # Force just says don't bother checking the copies, 
-        # because other code already has.
+        # If 'force' is set, the caller is saying that all copies have
+        # failed.  Otherwise, see if we have any copies left to inspect.
         return 1 if @{$self->copies} || $self->{valid_previous_copy};
     }
 
+    # At this point, all copies have been inspected and none 
+    # have yielded a targetable item.  
+
     if ($args{process_recalls}) {
-        # See if we have any copies to recall.
+        # See if we have any copies/circs to recall.
         return unless $self->process_recalls;
     }
     
@@ -874,6 +877,9 @@ sub find_nearest_copy {
     return undef;
 }
 
+# Returns true if the provided copy passes the hold permit test for our
+# hold and can be used for targeting.
+# When a copy fails the test, it is removed from $self->copies.
 sub copy_is_permitted {
     my ($self, $copy) = @_;
     return 0 unless $copy;
@@ -900,6 +906,7 @@ sub copy_is_permitted {
     return 0;
 }
 
+# Sets hold.current_copy to the provided copy.
 sub apply_copy_target {
     my ($self, $copy) = @_;
     my $e = $self->editor;
@@ -916,6 +923,7 @@ sub apply_copy_target {
     return $self->exit_targeter("Hold successfully targeted");
 }
 
+# Creates a new row in action.unfulfilled_hold_list for our hold.
 # Returns 1 if all is OK, false on error.
 sub log_unfulfilled_hold {
     my $self = shift;
@@ -1089,9 +1097,7 @@ sub target {
 
     return $self->apply_copy_target($copy) if $copy;
 
-    # No targetable copy was found.  Fire the no-copy 
-    # handler to update the hold accordingly.
-    
+    # No targetable copy was found.  Fire the no-copy handler.
     $self->handle_no_copies(force => 1, process_recalls => 1);
 }