net/dns: move mutex before the field it guards

And some misc doc tweaks for idiomatic Go style.

Updates #cleanup

Change-Id: I3ca45f78aaca037f433538b847fd6a9571a2d918
Signed-off-by: Brad Fitzpatrick <[email protected]>

net/dns/manager.go

@@ -59,11 +59,10 @@ type Manager struct {
 	knobs    *controlknobs.Knobs // or nil
 	goos     string              // if empty, gets set to runtime.GOOS
 
-	// The last configuration we successfully compiled.  Set to nil if
-	// there was any failure applying the last configuration
+	mu sync.Mutex // guards following
+	// config is the last configuration we successfully compiled or nil if there
+	// was any failure applying the last configuration.
 	config *Config
-	// Must be held when accessing/setting config.
-	mu sync.Mutex
 }
 
 // NewManagers created a new manager from the given config.
@@ -123,8 +122,9 @@ func (m *Manager) Set(cfg Config) error {
 	return m.setLocked(cfg)
 }
 
-// Sets the DNS configuration.
-// m.mu must be held
+// setLocked sets the DNS configuration.
+//
+// m.mu must be held.
 func (m *Manager) setLocked(cfg Config) error {
 	syncs.AssertLocked(&m.mu)
 

net/dns/resolver/forwarder.go

@@ -212,7 +212,9 @@ type forwarder struct {
 	// resolver lookup.
 	cloudHostFallback []resolverAndDelay
 
-	// To be called when a SERVFAIL is returned due to missing upstream resolvers.
+	// missingUpstreamRecovery, if non-nil, is set called when a SERVFAIL is
+	// returned due to missing upstream resolvers.
+	//
 	// This should attempt to properly (re)set the upstream resolvers.
 	missingUpstreamRecovery func()
 }

net/dns/resolver/tsdns.go

@@ -244,9 +244,11 @@ func New(logf logger.Logf, linkSel ForwardLinkSelector, dialer *tsdial.Dialer, k
 	return r
 }
 
-// Called by the forwarder on SERVFAIL due to missing upstream resolvers
-// The func passed in here should attempt to re-query for those resolvers,
-// repair, or recover
+// SetMissingUpstreamRecovery sets a callback to be called upon encountering
+// a SERVFAIL due to missing upstream resolvers.
+//
+// This call should only happen before the resolver is used. It is not safe
+// for concurrent use.
 func (r *Resolver) SetMissingUpstreamRecovery(f func()) {
 	r.forwarder.missingUpstreamRecovery = f
 }