clarify documentation a bit

reader.go

@@ -7,9 +7,9 @@ import (
 	"unsafe"
 )
 
-// FieldContext identifies a single protobuf-encoded field.
+// FieldContext represents a single protobuf-encoded field after NextField() call.
 type FieldContext struct {
-	// FieldNum is the field number
+	// FieldNum is the number of protobuf field read after NextField() call.
 	FieldNum uint32
 
 	// wireType is the wire type for the given field
@@ -264,7 +264,7 @@ func (fc *FieldContext) Double() (float64, bool) {
 
 // String returns string value for fc.
 //
-// The returned string is valid until the underlying buffer isn't changed.
+// The returned string is valid while the underlying buffer isn't changed.
 //
 // False is returned if fc doesn't contain string value.
 func (fc *FieldContext) String() (string, bool) {
@@ -277,7 +277,7 @@ func (fc *FieldContext) String() (string, bool) {
 
 // Bytes returns bytes value for fc.
 //
-// The returned byte slice is valid until the underlying buffer isn't changed.
+// The returned byte slice is valid while the underlying buffer isn't changed.
 //
 // False is returned if fc doesn't contain bytes value.
 func (fc *FieldContext) Bytes() ([]byte, bool) {

writer.go

@@ -33,9 +33,11 @@ func (mp *MarshalerPool) Put(m *Marshaler) {
 
 // Marshaler helps marshaling arbitrary protobuf messages.
 //
-// Construct message with Append* functions and then call Marshal* for marshaling the constructed message.
+// Construct message with Append* functions at MessageMarshaler() and then call Marshal* for marshaling the constructed message.
 //
-// It is recommended obtaining Marshaler via MarshalerPool in order to reduce memory allocations.
+// It is unsafe to use a single Marshaler instance from multiple concurrently running goroutines.
+//
+// It is recommended re-cycling Marshaler via MarshalerPool in order to reduce memory allocations.
 type Marshaler struct {
 	// mm contains the root MessageMarshaler.
 	mm *MessageMarshaler
@@ -113,6 +115,9 @@ func (m *Marshaler) Reset() {
 
 // MarshalWithLen marshals m, appends its length together with the marshaled m to dst and returns the result.
 //
+// E.g. appends length-delimited protobuf message to dst.
+// The length of the resulting message can be read via UnmarshalMessageLen() function.
+//
 // See also Marshal.
 func (m *Marshaler) MarshalWithLen(dst []byte) []byte {
 	if m.mm == nil {
@@ -134,6 +139,8 @@ func (m *Marshaler) MarshalWithLen(dst []byte) []byte {
 
 // Marshal appends marshaled protobuf m to dst and returns the result.
 //
+// The marshaled message can be read via FieldContext.NextField().
+//
 // See also MarshalWithLen.
 func (m *Marshaler) Marshal(dst []byte) []byte {
 	if m.mm == nil {
@@ -301,6 +308,8 @@ func (mm *MessageMarshaler) AppendBytes(fieldNum uint32, b []byte) {
 }
 
 // AppendMessage appends protobuf message with the given fieldNum to m.
+//
+// The function returns the MessageMarshaler for constructing the appended message.
 func (mm *MessageMarshaler) AppendMessage(fieldNum uint32) *MessageMarshaler {
 	tag := makeTag(fieldNum, wireTypeLen)