raft: add useful comments

These comments were things I learned about the units, use case or
meaning of various fields and functions in the raft package.

raft/node.go

@@ -1,4 +1,3 @@
-// Package raft implements raft.
 package raft
 
 import (
@@ -55,6 +54,8 @@ type Node struct {
 	done   chan struct{}
 }
 
+// Start returns a new Node given a unique raft id, a list of raft peers, and
+// the election and heartbeat timeouts in units of ticks.
 func Start(id int64, peers []int64, election, heartbeat int) Node {
 	n := newNode()
 	r := newRaft(id, peers, election, heartbeat)
@@ -62,6 +63,9 @@ func Start(id int64, peers []int64, election, heartbeat int) Node {
 	return n
 }
 
+// Restart is identical to Start but takes an initial State and a slice of
+// entries. Generally this is used when restarting from a stable storage
+// log.
 func Restart(id int64, peers []int64, election, heartbeat int, st pb.State, ents []pb.Entry) Node {
 	n := newNode()
 	r := newRaft(id, peers, election, heartbeat)
@@ -131,6 +135,8 @@ func (n *Node) run(r *raft) {
 	}
 }
 
+// Tick increments the internal logical clock for this Node. Election timeouts
+// and heartbeat timeouts are in units of ticks.
 func (n *Node) Tick() error {
 	select {
 	case n.tickc <- struct{}{}:

raft/raft.go

@@ -108,7 +108,7 @@ type raft struct {
 	// the leader id
 	lead int64
 
-	elapsed          int
+	elapsed          int // number of ticks since the last msg
 	heartbeatTimeout int
 	electionTimeout  int
 	tick             func()
@@ -258,6 +258,7 @@ func (r *raft) appendEntry(e pb.Entry) {
 	r.maybeCommit()
 }
 
+// tickElection is ran by followers and candidates after r.electionTimeout.
 func (r *raft) tickElection() {
 	r.elapsed++
 	// TODO (xiangli): elctionTimeout should be randomized.
@@ -267,6 +268,7 @@ func (r *raft) tickElection() {
 	}
 }
 
+// tickHeartbeat is ran by leaders to send a msgBeat after r.heartbeatTimeout.
 func (r *raft) tickHeartbeat() {
 	r.elapsed++
 	if r.elapsed > r.heartbeatTimeout {