Index: /branches/eam_branches/ipp-20191011/Nebulous/bin/neb-repair
===================================================================
--- /branches/eam_branches/ipp-20191011/Nebulous/bin/neb-repair	(revision 41047)
+++ /branches/eam_branches/ipp-20191011/Nebulous/bin/neb-repair	(revision 41048)
@@ -45,9 +45,10 @@
 );
 
-die "can't connected to Nebulous Server: $server"
+die "can't connect to Nebulous Server: $server"
     unless defined $neb;
 
 my $stat = $neb->stat($key);
 die "nebulous key: $key not found" unless $stat;   
+
 my $instances = $neb->find_instances($key, 'any');
 die "no instances found" unless $instances;   
@@ -71,4 +72,5 @@
 
 for (my $i = 0; $i <= $#files; $i++) {
+    # count existing files and get the MD5 sums
     if (-e $files[$i]) {
 	$existance[$i] = 1;
@@ -89,6 +91,5 @@
 	push @{ $md5sum_valid{$md5sums[$i]} }, $files[$i];
 	$last_f = $files[$i];
-    }
-    else {
+    } else {
 	$existance[$i] = 0;
 	$md5sums[$i] = 'NON-EXISTANT';
@@ -98,19 +99,23 @@
 }
 
+# check number of copies and number of unique MD5 sum values
 my $N_mds = scalar(keys(%md5sum_uniq));
 my $N_files = scalar(@files);
+
+# seems like we should not call neb-replicate until *after* we have
+# removed 0-byte copies
 if ($N_files < $user_copies) {
     print "Insufficient copies ($N_files) of $key, replicating!\n";
     system("neb-replicate $key");
 }
+
 if ($N_mds == 1) {
     print "Nebulous key $key is consistent.\n";
-}
-else {
+} else {
     my $valid_sum = '';
     my $valid_file = '';
     my $m;
     foreach $m (keys %md5sum_valid) {
-	if (($m ne 'd41d8cd98f00b204e9800998ecf8427e')&&($m ne 'NON-EXISTANT')) {
+	if (($m ne 'd41d8cd98f00b204e9800998ecf8427e') && ($m ne 'NON-EXISTANT')) {
 	    if ($valid_sum ne '') {
 		die "Too many acceptable files for key $key\n";
@@ -122,6 +127,5 @@
     if ($valid_sum eq '') {
 	die "No acceptable file for key $key\n";
-    }
-    else {
+    } else {
 	print "Repairing instances\n";
 	foreach $m (keys %md5sum_valid) {
@@ -130,20 +134,26 @@
 		    print "\tcp $valid_file $f\n";
 		    system("cp $valid_file $f");
+
+		    # if we failed to make a copy, the target ($f) could be inaccessible
 		    if ($? >> 8 != 0) {
 			if ($existance[0] == 1) {
-			    # We can fix this with culls and replications.
+
+			    # The target is a valid file 0-byte file
+			    # but we cannot replace it with the
+			    # correct file.  We can fix this with
+			    # culls and replications.
+
 			    print "Attempting to fix this.\n";
 			    print("neb-replicate $key\n");
 			    system("neb-replicate $key");
 			    if ($? >> 8 == 0) {
+				# if the neb-replicate succeeded, remove the bad copy with neb-cull
 				my $bad_volume = (split /\//, $f)[2];
 				print("neb-cull --volume $bad_volume $key\n");
 				system("neb-cull --volume $bad_volume $key");
-			    }
-			    else {
+			    } else {
 				die "Failed to copy file $valid_file to $f, and subsequent replication also failed!\n";
 			    }
-			}
-			else {
+			} else {
 			    die "Failed to copy file $valid_file to $f!\n";
 			}
@@ -187,5 +197,12 @@
 =head1 DESCRIPTION
 
-This program repairs instances and corrects instance counts for a nebulous key.  
+This program repairs instances and corrects instance counts for a nebulous key:
+
+If some of the existing instances have the MD5 sum corresponding to a
+0-byte file, but the rest have the same, non-zero byte md5sum, then
+replace the 0-byte files with the non-zero byte version.
+
+At the end, if the number of instances is less than the value of
+user.copies, then additional copies are generated.
 
 =head1 OPTIONS