scanhash: Document scanhash related methods with comments

deviceapi.c

@@ -239,7 +239,11 @@ void minerloop_scanhash(struct thr_info *mythr)
 			* it is not in the driver code. */
 			pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
 			timer_set_now(&tv_start);
+
+			/* api->scanhash should scan the work for valid nonces
+			 * until max_nonce is reached or thr_info->work_restart */
 			hashes = api->scanhash(mythr, work, work->blk.nonce + max_nonce);
+
 			timer_set_now(&tv_end);
 			pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
 			pthread_testcancel();
@@ -269,6 +273,10 @@ disabled:
 				mt_disable(mythr);
 			
 			timersub(&tv_end, &work->tv_work_start, &tv_worktime);
+
+		/* The inner do-while loop will exit unless the device is capable of
+		 * scanning a specific nonce range (currently CPU and GPU drivers)
+		 * See abandon_work comments for more details */
 		} while (!abandon_work(work, &tv_worktime, cgpu->max_hashes));
 		free_work(work);
 	}

miner.c

@@ -9667,12 +9667,16 @@ out:
 	return ret;
 }
 
-bool abandon_work(struct work *work, struct timeval *wdiff, uint64_t hashes)
-{
-	if (wdiff->tv_sec > opt_scantime ||
-	    work->blk.nonce >= 0xfffffffe - hashes ||
-	    hashes >= 0xfffffffe ||
-	    stale_work(work, false))
+// return true of we should stop working on this piece of work
+// returning false means we will keep scanning for a nonce
+// assumptions: work->blk.nonce is the number of nonces completed in the work
+// see minerloop_scanhash comments for more details & usage
+bool abandon_work(struct work *work, struct timeval *wdiff, uint64_t max_hashes)
+{
+	if (wdiff->tv_sec > opt_scantime ||                 // scan-time has elapsed (user specified, default 60s)
+	    work->blk.nonce >= 0xfffffffe - max_hashes ||   // are there enough nonces left in the work
+	    max_hashes >= 0xfffffffe ||                     // assume we are scanning a full nonce range
+	    stale_work(work, false))                        // work is stale
 		return true;
 	return false;
 }