commit 715bde910b784cb9602e304399e913502b8b658e
author Jacob MacDonald <jakemac@google.com> Wed Apr 05 08:43:32 2017 -0700
committer Jacob MacDonald <jakemac@google.com> Wed Apr 05 10:37:51 2017 -0700
tree 4caca4c706b6b561ffc6170267bed3441c57c520
parent 670f166d774f33d3d66dbf1b251bac29097854e0

update driver comments

lib/src/driver/driver.dart

diff --git a/lib/src/driver/driver.dart b/lib/src/driver/driver.dart
index 49ac3dc..9d0bb85 100644
--- a/lib/src/driver/driver.dart
+++ b/lib/src/driver/driver.dart
@@ -95,12 +95,12 @@
         _spawningWorkers.remove(futureWorker);
         _readyWorkers.add(worker);
 
-        // Set up the connection and run the worker.
         _workerConnections[worker] = new StdDriverConnection.forWorker(worker);
         _runWorker(worker, request);
 
-        // Clean up things when the worker exits, and retry running the work
-        // queue in case there is more work to be done.
+        // When the worker exits we should retry running the work queue in case
+        // there is more work to be done. This is primarily just a defensive
+        // thing but is cheap to do.
         worker.exitCode.then((_) {
           _readyWorkers.remove(worker);
           _runWorkQueue();

lib/src/driver/driver_connection.dart

diff --git a/lib/src/driver/driver_connection.dart b/lib/src/driver/driver_connection.dart
index 1624b28..787fcfd 100644
--- a/lib/src/driver/driver_connection.dart
+++ b/lib/src/driver/driver_connection.dart
@@ -1,4 +1,4 @@
-// Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
+// Copyright (c) 2017, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
@@ -9,12 +9,14 @@
 import '../worker_protocol.pb.dart';
 import '../utils.dart';
 
-/// Interface for a [DriverConnection].
+/// A connection from a `BazelWorkerDriver` to a worker.
+///
+/// Unlike `WorkerConnection` there is no synchronous version of this class.
+/// This is because drivers talk to multiple workers, so they should never block
+/// when waiting for the response of any individual worker.
 abstract class DriverConnection {
-  /// Reads a [WorkResponse] asynchronously.
   Future<WorkResponse> readResponse();
 
-  /// Writes a [WorkRequest].
   void writeRequest(WorkRequest request);
 }