Cleanup comments explaining the build logic

Author: earlephilhower

tests/common.sh

@@ -54,21 +54,26 @@ function build_sketches()
             continue  # Not ours to do
         fi
 
-        # Uber hack warning - setting the cached core.a file to the future to
-        # ensure it is accepted as unmodified during build process.  Problem is
-        # the git version header is rewritten after each compile, so the
-        # builder sees it is new and says "rebuild the whole thing!"
-
         if [ -e $cache_dir/core/*.a ]; then
+            # We need to preserve the build.options.json file and replace the last .ino
+            # with this sketch's ino file, or builder will throw everything away.  This
+            # head/tail easier than a complicated SED script to replace the 1 line we need.
             head -8 $build_dir/build.options.json > $build_dir/../build.options.json
             echo '  "sketchLocation" : "'$sketch'",' >> $build_dir/../build.options.json
             tail -2 $build_dir/build.options.json >> $build_dir/../build.options.json
         fi
 
+        # Clear out the last built sketch, map, elf, bin files, but leave the compiled
+        # objects in the core and libraries available for use so we don't need to rebuild
+        # them each sketch.
         rm -rf $build_dir/sketch $build_dir/*.bin $build_dir/*.map $build_dir/*.elf
 
         if [ -e $cache_dir/core/*.a ]; then
+            # Restore the new build.options.json file
             mv $build_dir/../build.options.json $build_dir/build.options.json
+            # Set the time of the cached core.a file to year 2037 so the GIT header
+            # we regen won't cause the builder to throw it out and rebuild from
+            # scratch.
             touch -t 203712310000 $cache_dir/core/*.a
         fi