improve doc comments for logBuffer & logClient

internals/overlord/logstate/gatherer.go

@@ -134,14 +134,23 @@ func (g *logGatherer) stop() {
 	close(g.cancel)
 }
 
-// logBuffer is an interface which ...
+// logBuffer is an interface encapsulating format-specific buffering of log
+// messages. E.g. a logBuffer for Loki would encode the log messages in the
+// JSON format expected by Loki.
 // A logBuffer's methods may not be concurrency-safe. Callers should protect
 // the logBuffer using a sync.Mutex.
 type logBuffer interface {
-	Write(servicelog.Entry)
 	IsEmpty() bool
 	IsFull() bool
+
+	// Write encodes the provided log message and adds it to the buffer.
+	Write(servicelog.Entry) // TODO: return error?
+
+	// Request returns an io.Reader which can be used as the body of a request
+	// to the remote log target.
 	Request() (io.Reader, error)
+
+	// Reset empties the buffer.
 	Reset()
 }
 
@@ -150,6 +159,8 @@ func newLogBuffer(target *plan.LogTarget) logBuffer {
 	return nil
 }
 
+// logClient is implemented by a client to a specific type of log target.
+// It sends requests using the protocol preferred by that log target.
 type logClient interface {
 	Send(io.Reader) error
 }