Merge pull request #7046 from C-Otto/watchtower-docu-fixes

watchtower: docu fixes

watchtower/wtclient/client.go

@@ -266,9 +266,9 @@ type TowerClient struct {
 var _ Client = (*TowerClient)(nil)
 
 // New initializes a new TowerClient from the provide Config. An error is
-// returned if the client could not initialized.
+// returned if the client could not be initialized.
 func New(config *Config) (*TowerClient, error) {
-	// Copy the config to prevent side-effects from modifying both the
+	// Copy the config to prevent side effects from modifying both the
 	// internal and external version of the Config.
 	cfg := new(Config)
 	*cfg = *config
@@ -739,7 +739,7 @@ func (c *TowerClient) nextSessionQueue() (*sessionQueue, error) {
 		return nil, err
 	}
 
-	// Initialize the session queue and spin it up so it can begin handling
+	// Initialize the session queue and spin it up, so it can begin handling
 	// updates. If the queue was already made active on startup, this will
 	// simply return the existing session queue from the set.
 	return c.getOrInitActiveQueue(candidateSession, updates), nil
@@ -891,7 +891,7 @@ func (c *TowerClient) backupDispatcher() {
 }
 
 // processTask attempts to schedule the given backupTask on the active
-// sessionQueue. The task will either be accepted or rejected, afterwhich the
+// sessionQueue. The task will either be accepted or rejected, after which the
 // appropriate modifications to the client's state machine will be made. After
 // every invocation of processTask, the caller should ensure that the
 // sessionQueue hasn't been exhausted before proceeding to the next task. Tasks
@@ -934,15 +934,15 @@ func (c *TowerClient) taskAccepted(task *backupTask, newStatus reserveStatus) {
 		c.log.Debugf("Session %s exhausted", c.sessionQueue.ID())
 
 		// This task left the session exhausted, set it to nil and
-		// proceed to the next loop so we can consume another
+		// proceed to the next loop, so we can consume another
 		// pre-negotiated session or request another.
 		c.sessionQueue = nil
 	}
 }
 
 // taskRejected process the rejection of a task by a sessionQueue depending on
 // the state the was in *before* the task was rejected. The client's prevTask
-// will cache the task if the sessionQueue was exhausted before hand, and nil
+// will cache the task if the sessionQueue was exhausted beforehand, and nil
 // the sessionQueue to find a new session. If the sessionQueue was not
 // exhausted, the client marks the task as ineligible, as this implies we
 // couldn't construct a valid justice transaction given the session's policy.
@@ -1088,7 +1088,7 @@ func (c *TowerClient) newSessionQueue(s *wtdb.ClientSession,
 
 // getOrInitActiveQueue checks the activeSessions set for a sessionQueue for the
 // passed ClientSession. If it exists, the active sessionQueue is returned.
-// Otherwise a new sessionQueue is initialized and added to the set.
+// Otherwise, a new sessionQueue is initialized and added to the set.
 func (c *TowerClient) getOrInitActiveQueue(s *wtdb.ClientSession,
 	updates []wtdb.CommittedUpdate) *sessionQueue {
 
@@ -1106,8 +1106,8 @@ func (c *TowerClient) getOrInitActiveQueue(s *wtdb.ClientSession,
 func (c *TowerClient) initActiveQueue(s *wtdb.ClientSession,
 	updates []wtdb.CommittedUpdate) *sessionQueue {
 
-	// Initialize the session queue, providing it with all of the resources
-	// it requires from the client instance.
+	// Initialize the session queue, providing it with all the resources it
+	// requires from the client instance.
 	sq := c.newSessionQueue(s, updates)
 
 	// Add the session queue as an active session so that we remember to

watchtower/wtclient/interface.go

@@ -57,11 +57,9 @@ type DB interface {
 	// restarts.
 	CreateClientSession(*wtdb.ClientSession) error
 
-	// ListClientSessions returns all sessions that have not yet been
-	// exhausted. This is used on startup to find any sessions which may
-	// still be able to accept state updates. An optional tower ID can be
-	// used to filter out any client sessions in the response that do not
-	// correspond to this tower.
+	// ListClientSessions returns the set of all client sessions known to
+	// the db. An optional tower ID can be used to filter out any client
+	// sessions in the response that do not correspond to this tower.
 	ListClientSessions(*wtdb.TowerID, ...wtdb.ClientSessionListOption) (
 		map[wtdb.SessionID]*wtdb.ClientSession, error)
 

watchtower/wtclient/session_queue.go

@@ -81,7 +81,7 @@ type sessionQueueConfig struct {
 // backups to the watchtower specified in the config's ClientSession. Calling
 // Quit will attempt to perform a clean shutdown by receiving an ACK from the
 // tower for all pending backups before exiting. The clean shutdown can be
-// aborted by using ForceQuit, which will attempt to shutdown the queue
+// aborted by using ForceQuit, which will attempt to shut down the queue
 // immediately.
 type sessionQueue struct {
 	started sync.Once
@@ -108,7 +108,7 @@ type sessionQueue struct {
 	shutdown  chan struct{}
 }
 
-// newSessionQueue intiializes a fresh sessionQueue.
+// newSessionQueue initializes a fresh sessionQueue.
 func newSessionQueue(cfg *sessionQueueConfig,
 	updates []wtdb.CommittedUpdate) *sessionQueue {
 
@@ -275,7 +275,7 @@ func (q *sessionQueue) sessionManager() {
 		}
 		q.queueCond.L.Unlock()
 
-		// Exit immediately if a force quit has been requested.  If the
+		// Exit immediately if a force quit has been requested.  If
 		// either of the queues still has state updates to send to the
 		// tower, we may never exit in the above case if we are unable
 		// to reach the tower for some reason.
@@ -314,7 +314,7 @@ func (q *sessionQueue) drainBackups() {
 	// Init.
 	for sendInit := true; ; sendInit = false {
 		// Generate the next state update to upload to the tower. This
-		// method will first proceed in dequeueing committed updates
+		// method will first proceed in dequeuing committed updates
 		// before attempting to dequeue any pending updates.
 		stateUpdate, isPending, backupID, err := q.nextStateUpdate()
 		if err != nil {
@@ -480,8 +480,8 @@ func (q *sessionQueue) nextStateUpdate() (*wtwire.StateUpdate, bool,
 // the ACK before returning. If sendInit is true, this method will first send
 // the localInit message and verify that the tower supports our required feature
 // bits. And error is returned if any part of the send fails. The boolean return
-// variable indicates whether or not we should back off before attempting to
-// send the next state update.
+// variable indicates whether we should back off before attempting to send the
+// next state update.
 func (q *sessionQueue) sendStateUpdate(conn wtserver.Peer,
 	stateUpdate *wtwire.StateUpdate, localInit *wtwire.Init,
 	sendInit, isPending bool) error {
@@ -598,10 +598,10 @@ func (q *sessionQueue) sendStateUpdate(conn wtserver.Peer,
 	return nil
 }
 
-// reserveStatus returns a reserveStatus indicating whether or not the
-// sessionQueue can accept another task. reserveAvailable is returned when a
-// task can be accepted, and reserveExhausted is returned if the all slots in
-// the session have been allocated.
+// reserveStatus returns a reserveStatus indicating whether the sessionQueue can
+// accept another task. reserveAvailable is returned when a task can be
+// accepted, and reserveExhausted is returned if the all slots in the session
+// have been allocated.
 //
 // NOTE: This method MUST be called with queueCond's exclusive lock held.
 func (q *sessionQueue) reserveStatus() reserveStatus {

watchtower/wtclient/stats.go

@@ -31,7 +31,7 @@ type ClientStats struct {
 	NumSessionsExhausted int
 }
 
-// taskReceived increments the number to backup requests the client has received
+// taskReceived increments the number of backup requests the client has received
 // from active channels.
 func (s *ClientStats) taskReceived() {
 	s.mu.Lock()
@@ -74,7 +74,7 @@ func (s *ClientStats) sessionExhausted() {
 	s.NumSessionsExhausted++
 }
 
-// String returns a human readable summary of the client's metrics.
+// String returns a human-readable summary of the client's metrics.
 func (s *ClientStats) String() string {
 	s.mu.Lock()
 	defer s.mu.Unlock()

watchtower/wtdb/client_db.go

@@ -1147,7 +1147,7 @@ func (c *ClientDB) AckUpdate(id *SessionID, seqNum uint16,
 			return err
 		}
 
-		// Ensure that the session acks sub-bucket is initialized so we
+		// Ensure that the session acks sub-bucket is initialized, so we
 		// can insert an entry.
 		sessionAcks, err := sessionBkt.CreateBucketIfNotExists(
 			cSessionAcks,

watchtower/wtwire/delete_session_reply.go

@@ -15,8 +15,7 @@ const (
 )
 
 // DeleteSessionReply is a message sent in response to a client's DeleteSession
-// request. The message indicates whether or not the deletion was a success or
-// failure.
+// request. The message indicates whether the deletion was a success or failure.
 type DeleteSessionReply struct {
 	// Code will be non-zero if the watchtower was not able to delete the
 	// requested session.