Fix some small comments

balancer.go

@@ -66,7 +66,8 @@ type BalancerGetOptions struct {
 // This is the EXPERIMENTAL API and may be changed or extended in the future.
 type Balancer interface {
 	// Start does the initialization work to bootstrap a Balancer. For example,
-	// this function may start the name resolution and watch the updates.
+	// this function may start the name resolution and watch the updates. It will
+	// be called when dialing.
 	Start(target string) error
 	// Up informs the Balancer that gRPC has a connection to the server at
 	// addr. It returns down which is called once the connection to addr gets

clientconn.go

@@ -698,14 +698,14 @@ func (ac *addrConn) tearDown(err error) {
 		}
 		ac.cc.mu.Unlock()
 	}()
-	if ac.down != nil {
-		ac.down(downErrorf(false, false, "%v", err))
-		ac.down = nil
-	}
 	if ac.state == Shutdown {
 		return
 	}
 	ac.state = Shutdown
+	if ac.down != nil {
+		ac.down(downErrorf(false, false, "%v", err))
+		ac.down = nil
+	}
 	ac.stateCV.Broadcast()
 	if ac.events != nil {
 		ac.events.Finish()

naming/naming.go

@@ -66,8 +66,8 @@ type Resolver interface {
 // Watcher watches for the updates on the specified target.
 type Watcher interface {
 	// Next blocks until an update or error happens. It may return one or more
-	// updates. The first call should get the full set of the results. It only
-	// returns the error Watcher cannot recover.
+	// updates. The first call should get the full set of the results. It should
+	// return an error if and only if Watcher cannot recover.
 	Next() ([]*Update, error)
 	// Close closes the Watcher.
 	Close()

transport/http2_client.go

@@ -398,7 +398,6 @@ func (t *http2Client) CloseStream(s *Stream, err error) {
 	t.mu.Lock()
 	if t.activeStreams == nil {
 		t.mu.Unlock()
-		t.Close()
 		return
 	}
 	if t.streamsQuota != nil {