Update comments

internal/serde/reflect.go

@@ -228,9 +228,8 @@ func serializePointedAt(s *Serializer, t reflect.Type, p unsafe.Pointer) {
 	// Check the region of this pointer.
 	r := s.containers.of(p)
 
-	// If this pointer does not belong to any region or is the container of
-	// the region, write a negative offset to flag it is on its own, and
-	// write its data.
+	// If this pointer does not belong to any region, write a negative
+	// offset to flag it is on its own, and write its data.
 	if !r.valid() {
 		serializeVarint(s, -1)
 		SerializeAny(s, t, p)
@@ -244,8 +243,10 @@ func serializePointedAt(s *Serializer, t reflect.Type, p unsafe.Pointer) {
 	// Write the type of the container.
 	serializeType(s, r.typ)
 
-	// Serialize the parent.
-
+	// Serialize the parent. If offset is zero, we reuse the id to store the
+	// parent. We could have a more compact representation here, but right
+	// now we need this since the pointers <> id map in the serializer does
+	// not discriminate between the container and the first element of it.
 	if offset == 0 {
 		serializeVarint(s, int(id))
 		serializeVarint(s, -1)

internal/serde/serde.go

@@ -90,9 +90,8 @@ func (d *Deserializer) store(i sID, p unsafe.Pointer) {
 // This mechanism allows writing shared data only once. The actual value is
 // written the first time a given pointer ID is encountered.
 //
-// The regions value contains ranges of memory held by container types. They are
-// the values that actually own memory: basic types (bool, numbers), structs,
-// and arrays.
+// The containers value has ranges of memory held by container types. They are
+// the values that actually own memory: structs and arrays.
 //
 // Serialization starts with scanning the graph of values to find all the
 // containers and add the range of memory they occupy into the map. Regions
@@ -104,7 +103,7 @@ func (d *Deserializer) store(i sID, p unsafe.Pointer) {
 //	  }
 //	}
 //
-// creates only one region: the struct X. Both struct Y and the int are
+// creates only one container: the struct X. Both struct Y and the int are
 // containers, but they are included in the region of struct X.
 //
 // Those two mechanisms allow the deserialization of pointers that point to