Apply suggestions from code review

Improves/rewrites/fixes many doc strings

Co-authored-by: Lin Zhihao <[email protected]>

ir/deserializer.go

@@ -17,7 +17,7 @@ import (
 )
 
 // A Deserializer exports functions to deserialize log events from a CLP IR byte
-// stream. Deserializatoin functions take an IR buffer as input, but how that
+// stream. Deserialization functions take an IR buffer as input, but how that
 // buffer is materialized is left to the user. These functions return views
 // (slices) of the log events extracted from the IR. Each Deserializer owns its
 // own unique underlying memory for the views it produces/returns. This memory
@@ -173,6 +173,16 @@ func (self *fourByteDeserializer) DeserializeLogEvent(
 	return deserializeLogEvent(self, irBuf)
 }
 
+// DeserializeWildcardMatch attempts to read the next log event from the IR
+// stream in irBuf that matches mergedQuery within timeInterval. It returns the
+// deserialized [ffi.LogEventView], the position read to in irBuf (the end of
+// the log event in irBuf), the index of the matched query in mergedQuery,
+// and an error. On error returns:
+//   - nil *ffi.LogEventView
+//   - 0 position
+//   - -1 index
+//   - [IrError] error: CLP failed to successfully deserialize
+//   - [EndOfIr] error: CLP found the IR stream EOF tag
 func (self *eightByteDeserializer) DeserializeWildcardMatch(
 	irBuf []byte,
 	timeInterval search.TimestampInterval,
@@ -181,6 +191,16 @@ func (self *eightByteDeserializer) DeserializeWildcardMatch(
 	return deserializeWildcardMatch(self, irBuf, timeInterval, mergedQuery)
 }
 
+// DeserializeWildcardMatch attempts to read the next log event from the IR
+// stream in irBuf that matches mergedQuery within timeInterval. It returns the
+// deserialized [ffi.LogEventView], the position read to in irBuf (the end of
+// the log event in irBuf), the index of the matched query in mergedQuery,
+// and an error. On error returns:
+//   - nil *ffi.LogEventView
+//   - 0 position
+//   - -1 index
+//   - [IrError] error: CLP failed to successfully deserialize
+//   - [EndOfIr] error: CLP found the IR stream EOF tag
 func (self *fourByteDeserializer) DeserializeWildcardMatch(
 	irBuf []byte,
 	timeInterval search.TimestampInterval,

ir/ir.go

@@ -29,10 +29,10 @@ type TimestampInfo struct {
 	TimeZoneId    string
 }
 
-// ir.BufView is a slice of CLP IR backed by C++ allocated memory rather than
-// the Go heap. A BufView, x, is valid when returned and will remain valid until
-// a new BufView is returned by the same object (e.g. an [ir.Serializer]) that
-// retuend x.
+// ir.BufView represents a slice of CLP IR, utilizing memory allocated by C++
+// instead of the Go heap. A BufView, denoted as x, is valid upon being returned
+// and maintains its validity until the same object (e.g., an [ir.Serializer])
+// that issued x returns a new BufView.
 type BufView = []byte
 
 // A ir.LogMessage contains all the different components of a log message
@@ -44,10 +44,10 @@ type LogMessage[T EightByteEncoding | FourByteEncoding] struct {
 	DictVarEndOffsets []int32
 }
 
-// A ir.LogMessageView is a [ir.LogMessage] that is backed by C++ allocated
-// memory rather than the Go heap. A LogMessageView, x, is valid when returned
-// and will remain valid until a new LogMessageView is returned by the same
-// object (e.g.  an [ir.Encoder]) that retuend x.
+// ir.LogMessageView is a [ir.LogMessage] using memory allocated by C++ instead
+// of the Go heap. A LogMessageView, denoted as x, is valid upon being returned
+// and maintains its validity until the same object (e.g., an [ir.Encoder])
+// that issued x returns a new LogMessageView.
 type LogMessageView[T EightByteEncoding | FourByteEncoding] struct {
 	LogMessage[T]
 }

ir/serializer.go

@@ -92,8 +92,8 @@ type commonSerializer struct {
 	cptr   unsafe.Pointer
 }
 
-// Close will delete the underlying C++ allocated memory used by the
-// deserializer. Failure to call Close will result in a memory leak.
+// Closes the serializer by releasing the underlying C++ allocated memory.
+// Failure to call Close will result in a memory leak.
 func (self *commonSerializer) Close() error {
 	if nil != self.cptr {
 		C.ir_serializer_close(self.cptr)
@@ -111,7 +111,7 @@ type eightByteSerializer struct {
 	commonSerializer
 }
 
-// SerializeLogEvent attempts to serialize the log event, event, into a eight
+// SerializeLogEvent attempts to serialize the log event, event, into an eight
 // byte encoded CLP IR byte stream. On error returns:
 //   - a nil BufView
 //   - [IrError] based on the failure of the Cgo call

ir/writer.go

@@ -125,7 +125,8 @@ func (self *Writer) Write(event ffi.LogEvent) (int, error) {
 // [self.Bytes] and [self.Reset] to manually handle the buffer's contents before
 // continuing. Returns:
 //   - success: number of bytes written, nil
-//   - error: number of bytes written, error propagated from [bytes.Buffer.WriteTo]
+//   - error: number of bytes written, error propagated from
+//     [bytes.Buffer.WriteTo]
 func (self *Writer) WriteTo(w io.Writer) (int64, error) {
 	n, err := self.buf.WriteTo(w)
 	if nil == err {