--- loncom/interface/lonnavmaps.pm	2002/11/14 21:36:23	1.106
+++ loncom/interface/lonnavmaps.pm	2002/11/15 17:30:33	1.107
@@ -2,7 +2,7 @@
 # The LearningOnline Network with CAPA
 # Navigate Maps Handler
 #
-# $Id: lonnavmaps.pm,v 1.106 2002/11/14 21:36:23 bowersj2 Exp $
+# $Id: lonnavmaps.pm,v 1.107 2002/11/15 17:30:33 bowersj2 Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -1284,6 +1284,11 @@ sub min {
     if ($a < $b) { return $a; } else { return $b; }
 }
 
+# In the CVS repository, documentation of this algorithm is included 
+# in /doc/lonnavdocs, as a PDF and .tex source. Markers like **1**
+# will reference the same location in the text as the part of the
+# algorithm is running through.
+
 sub new {
     # magic invocation to create a class instance
     my $proto = shift;
@@ -1326,6 +1331,8 @@ sub new {
 
     my $maxDepth = 0; # tracks max depth
 
+    # **1**
+
     foreach my $pass (@iterations) {
         my $direction = $pass->[0];
         my $valName = $pass->[1];
@@ -1351,12 +1358,12 @@ sub new {
                 my $nextResources = $curRes->$nextResourceMethod();
                 my $resourceCount = scalar(@{$nextResources});
 
-                if ($resourceCount == 1) {
+                if ($resourceCount == 1) { # **3**
                     my $current = $nextResources->[0]->{DATA}->{$valName} || 999999999;
                     $nextResources->[0]->{DATA}->{$valName} = min($resultingVal, $current);
                 }
                 
-                if ($resourceCount > 1) {
+                if ($resourceCount > 1) { # **4**
                     foreach my $res (@{$nextResources}) {
                         my $current = $res->{DATA}->{$valName} || 999999999;
                         $res->{DATA}->{$valName} = min($current, $resultingVal + 1);
@@ -1364,7 +1371,7 @@ sub new {
                 }
             }
             
-            # Assign the final val
+            # Assign the final val (**2**)
             if (ref($curRes) && $direction == BACKWARD()) {
                 my $finalDepth = min($curRes->{DATA}->{TOP_DOWN_VAL},
                                      $curRes->{DATA}->{BOT_UP_VAL});
@@ -1386,7 +1393,7 @@ sub new {
         push @{$self->{STACK}}, [];
     }
 
-    # Prime the recursion w/ the first resource
+    # Prime the recursion w/ the first resource **5**
     push @{$self->{STACK}->[0]}, $self->{FIRST_RESOURCE};
     $self->{ALREADY_SEEN}->{$self->{FIRST_RESOURCE}->{ID}} = 1;
 
@@ -1435,8 +1442,8 @@ sub next {
     my $newDepth;
     my $here;
     while ( $i >= 0 && !$found ) {
-        if ( scalar(@{$self->{STACK}->[$i]}) > 0 ) {
-            $here = pop @{$self->{STACK}->[$i]};
+        if ( scalar(@{$self->{STACK}->[$i]}) > 0 ) { # **6**
+            $here = pop @{$self->{STACK}->[$i]}; # **7**
             $found = 1;
             $newDepth = $i;
         }
@@ -1456,7 +1463,7 @@ sub next {
 
     # If this is not a resource, it must be an END_BRANCH marker we want
     # to return directly.
-    if (!ref($here)) {
+    if (!ref($here)) { # **8**
         if ($here == END_BRANCH()) { # paranoia, in case of later extension
             $self->{CURRENT_DEPTH}--;
             return $here;
@@ -1504,7 +1511,7 @@ sub next {
     # one level lower. Thus, this is the end of the branch, since there are no
     # more resources added to this level or above.
     my $isEndOfBranch = $maxDepthAdded < $self->{CURRENT_DEPTH};
-    if ($isEndOfBranch) {
+    if ($isEndOfBranch) { # **9**
         push @{$self->{STACK}->[$self->{CURRENT_DEPTH}]}, END_BRANCH();
     }