Miscellaneous doc fixes.

pkg/log/log.go

@@ -123,7 +123,9 @@ func (txtype TxType) String() string {
 type Reason uint8
 
 const (
-	// ReasonUnknown is rarely generated from log reads.
+	// ReasonUnknown is the reason for raw transactions (since
+	// they are not grouped with the transaction for the event
+	// that initiated the logged event).
 	ReasonUnknown Reason = Reason(C.VSL_r_unknown)
 
 	// HTTP1 indicates the start of an HTTP/1 session.
@@ -148,8 +150,9 @@ const (
 	// BgFetch is a backend fetch in the background.
 	BgFetch = Reason(C.VSL_r_bgfetch)
 
-	// Pipe exchangrd bytes with a backend until one or the other
-	// side closes the connection.
+	// Pipe is an exchange of requests and responses between a
+	// client and backend with no intervention by Varnish, until
+	// one or the other side closes the connection.
 	Pipe = Reason(C.VSL_r_pipe)
 )
 
@@ -299,9 +302,9 @@ func (tag Tag) Nonprintable() bool {
 }
 
 // A Record in the Varnish log, corresponding to a line of output from
-// the varnishlog utility. Instances of this type are contained in the
-// Tx objects returned by Read() operations, and form the bulk of log
-// data.
+// the varnishlog utility. Instances of this type are returned for log
+// reads, possibly aggregated into transactions (the Tx type), and
+// form the bulk of log data.
 //
 // The contents and format of log records are described in vsl(7):
 //
@@ -372,7 +375,12 @@ type Tx struct {
 	Records []Record
 }
 
-// A Log instance is a client for the native logging interface.
+// A Log instance is the foundation for log access via the native
+// interface. It can be used to attach to the log of a live instance
+// of Varnish, create a Cursor object, and set include/exclude filters
+// for the records to be read from the log.
+//
+// XXX include/exclude filters not yet implemented
 type Log struct {
 	vsl     *C.struct_VSL_data
 	vsm     *vsm.VSM
@@ -454,8 +462,8 @@ func (log *Log) initVSM() error {
 }
 
 // AttachTmo sets the timeout for attaching to a Varnish instance.
-// The timeout tmo is rounded to seconds toward 0s. If tmo >= 0s, then
-// wait that many seconds to attach. If the tmo < 0s, wait
+// The timeout is truncated to seconds. If the truncated timeout >=
+// 0s, then wait that many seconds to attach. If the tmo < 0s, wait
 // indefinitely. By default, the Varnish default timeout holds (5s in
 // recent Varnish versions).
 func (log *Log) AttachTmo(tmo time.Duration) error {
@@ -485,7 +493,8 @@ func (log *Log) Attach(name string) error {
 }
 
 // Status classifies the current state of a log read sequence. A value
-// of this type is passed to the ReadHandler used by the Read method.
+// of this type is returned from the Cursor.Next() and
+// Query.NextTxGroup() methods.
 type Status int8
 
 const (

pkg/log/query.go

@@ -100,7 +100,7 @@ func (c *Cursor) NewQuery(grp Grouping, query string) (*Query, error) {
 // log. Transactions are aggregated according to the Grouping argument
 // given in NewQuery().
 //
-// The Status return values indicates whether there was an error
+// The Status return value indicates whether there was an error
 // reading the log, whether there was an end condition (EOL or EOF),
 // or if there are more transactions to be read from the log.
 func (q *Query) NextTxGroup() ([]Tx, Status) {