docs(scripts): notes on karma sharding

Author: chirayuk

scripts/travis/build.sh

@@ -123,9 +123,9 @@ _run_karma_tests() {(
   export -f _run_once
 
   if [[ $TESTS == "dart2js" ]]; then
+    # Ref: test/_specs.dart: _numKarma shards.
     # Prime the dart2jsaas cache.
     NUM_KARMA_SHARDS=0 BROWSERS=SL_Chrome _run_once 0
-
     # Run sharded karma tests.
     export NUM_KARMA_SHARDS=4
     seq 0 $((NUM_KARMA_SHARDS-1)) | xargs -n 1 -P $NUM_KARMA_SHARDS -I SHARD_ID \

test/_specs.dart

@@ -132,6 +132,20 @@ void afterEach(Function fn) {
 }
 
 // For sharding across multiple instances of karma.
+// _numKarmaShards values:
+//   1:   (default) Use one shard. (i.e. there's no sharding.)
+//   0:   No shards!  So no tests are run.  However, the preprocessors are still
+//        executed and the browsers are launched.  This can be used to validate
+//        the configuration and browsers without running any tests.
+//        scripts/travis/build.sh uses this to run the preprocessors once to
+//        generate the dart2js output.  It then runs the tests with multiple
+//        shards knowing that these shards will all use the dart2js output
+//        generated from the dummy run.
+//   > 1: Specifies that there are this many number of total karma shards.  If
+//        there are N karma shards and T tests, then each shard runs about T/N
+//        tests.  In this case, the _shardId - which must be [0, N) - indicates
+//        the current karma shard so we can select the appropriate subset of
+//        tests to run.
 int _numShards = 1;
 int _shardId = 0;
 int _itCount = 0;