clarify ccomments, esp related to leadership code

api/api.go

@@ -943,7 +943,10 @@ func decodeBody(resp *http.Response, out interface{}) error {
 	}
 }
 
-// encodeBody is used to encode a request body
+// encodeBody prepares the reader to serve as the request body.
+//
+// Returns the `obj` input if it is a raw io.Reader object; otherwise
+// returns a reader of the json format of the passed argument.
 func encodeBody(obj interface{}) (io.Reader, error) {
 	if reader, ok := obj.(io.Reader); ok {
 		return reader, nil

nomad/leader.go

@@ -190,13 +190,16 @@ WAIT:
 		case member := <-reconcileCh:
 			s.reconcileMember(member)
 		case errCh := <-s.reassertLeaderCh:
-			// we can get into this state when the initial
-			// establishLeadership has failed as well as the follow
-			// up leadershipTransfer. Afterwards we will be waiting
-			// for the interval to trigger a reconciliation and can
-			// potentially end up here. There is no point to
-			// reassert because this agent was never leader in the
-			// first place.
+			// Recompute leader state, by asserting leadership and
+			// repopulating leader states.
+
+			// Check first if we are indeed the leaders first. We
+			// can get into this state when the initial
+			// establishLeadership has failed.
+			// Afterwards we will be waiting for the interval to
+			// trigger a reconciliation and can potentially end up
+			// here. There is no point to reassert because this
+			// agent was never leader in the first place.
 			if !establishedLeader {
 				errCh <- fmt.Errorf("leadership has not been established")
 				continue

nomad/operator_endpoint.go

@@ -553,8 +553,8 @@ func (op *Operator) snapshotRestore(conn io.ReadWriteCloser) {
 	lerrCh := make(chan error, 1)
 
 	select {
-	// Tell the leader loop to reassert leader actions since we just
-	// replaced the state store contents.
+	// Reassert leader actions and update all leader related state
+	// with new state store content.
 	case op.srv.reassertLeaderCh <- lerrCh:
 
 	// We might have lost leadership while waiting to kick the loop.

nomad/server.go

@@ -108,7 +108,12 @@ type Server struct {
 	raftInmem     *raft.InmemStore
 	raftTransport *raft.NetworkTransport
 
-	// reassertLeaderCh is used to signal the leader loop should re-run
+	// reassertLeaderCh is used to signal that the leader loop must
+	// re-establish leadership.
+	//
+	// This might be relevant in snapshot restores, where leader in-memory
+	// state changed significantly such that leader state (e.g. periodic
+	// jobs, eval brokers) need to be recomputed.
 	reassertLeaderCh chan chan error
 
 	// autopilot is the Autopilot instance for this server.