encoding/gob: document CommonType

Also bring the names in doc.go in line with the source.
More radical resolutions are possible but require substantial internal
changes for very little benefit. Fixing it this way lets us keep the
embedding, which has a huge simplifying effect, and guarantees
binary compatibility.

Fixes #2848.

R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/5644045

diff --git a/src/pkg/encoding/gob/doc.go b/src/pkg/encoding/gob/doc.go
index fce6879f56deea564861e44cf0dd8e655803ec55..c9ad18e764199a243e7386bd0680692cf4400698 100644 (file)
--- a/src/pkg/encoding/gob/doc.go
+++ b/src/pkg/encoding/gob/doc.go
@@ -162,7 +162,7 @@ description, constructed from these types:
                StructT *StructType
                MapT    *MapType
        }
-       type ArrayType struct {
+       type arrayType struct {
                CommonType
                Elem typeId
                Len  int
@@ -171,19 +171,19 @@ description, constructed from these types:
                Name string // the name of the struct type
                Id  int    // the id of the type, repeated so it's inside the type
        }
-       type SliceType struct {
+       type sliceType struct {
                CommonType
                Elem typeId
        }
-       type StructType struct {
+       type structType struct {
                CommonType
                Field []*fieldType // the fields of the struct.
        }
-       type FieldType struct {
+       type fieldType struct {
                Name string // the name of the field.
                Id   int    // the type id of the field, which must be already defined
        }
-       type MapType struct {
+       type mapType struct {
                CommonType
                Key  typeId
                Elem typeId
@@ -308,15 +308,15 @@ reserved).
        // Set the field number implicitly to -1; this is done at the beginning
        // of every struct, including nested structs.
        03      // Add 3 to field number; now 2 (wireType.structType; this is a struct).
-               // structType starts with an embedded commonType, which appears
+               // structType starts with an embedded CommonType, which appears
                // as a regular structure here too.
-       01      // add 1 to field number (now 0); start of embedded commonType.
+       01      // add 1 to field number (now 0); start of embedded CommonType.
        01      // add 1 to field number (now 0, the name of the type)
        05      // string is (unsigned) 5 bytes long
-       50 6f 69 6e 74  // wireType.structType.commonType.name = "Point"
+       50 6f 69 6e 74  // wireType.structType.CommonType.name = "Point"
        01      // add 1 to field number (now 1, the id of the type)
-       ff 82   // wireType.structType.commonType._id = 65
-       00      // end of embedded wiretype.structType.commonType struct
+       ff 82   // wireType.structType.CommonType._id = 65
+       00      // end of embedded wiretype.structType.CommonType struct
        01      // add 1 to field number (now 1, the field array in wireType.structType)
        02      // There are two fields in the type (len(structType.field))
        01      // Start of first field structure; add 1 to get field number 0: field[0].name

diff --git a/src/pkg/encoding/gob/type.go b/src/pkg/encoding/gob/type.go
index 71a28be7cab8a7a497145f9fdd692f95ab5dadc8..39006efdb2d596a553899fa778df42cb1e91cd84 100644 (file)
--- a/src/pkg/encoding/gob/type.go
+++ b/src/pkg/encoding/gob/type.go
@@ -180,7 +180,10 @@ func (t typeId) name() string {
        return t.gobType().name()
 }
 
-// Common elements of all types.
+// CommonType holds elements of all types.
+// It is a historical artifact, kept for binary compatibility and exported
+// only for the benefit of the package's encoding of type descriptors. It is
+// not intended for direct use by clients.
 type CommonType struct {
        Name string
        Id   typeId