codec: SelfExt: move documentation to proper location

codec/selfext.go

@@ -5,6 +5,22 @@ package codec
 
 import "sync"
 
+// This extension expects that types registered with it implement SelfExt interface.
+//
+// This is used by libraries that support BytesExt e.g. cbor, json.
+var GlobalSelfInterfaceExt InterfaceExt = selfInterfaceExt{}
+
+// var selfExtEncPool = sync.Pool{
+// 	New: func() interface{} { return new(Encoder) },
+// }
+// var selfExtDecPool = sync.Pool{
+// 	New: func() interface{} { return new(Decoder) },
+// }
+
+// SelfExt is the interface that users implement so that their types
+// can, with minimal effort, be able to be an extension while allowing the
+// library handling the encoding/decoding needs easily.
+//
 // We now support the ability for an extension to define a tag,
 // but allow itself to be encoded in a default way.
 //
@@ -31,53 +47,40 @@ import "sync"
 //        // ... all t fields
 //    }
 //
-// To use:
+// Usage model:
 //
 //    cborHandle.SetInterfaceExt(reflect.TypeOf(T), 122, codec.GlobalSelfInterfaceExt)
 //
 //    msgpackHandle.SetBytesExt(reflect.TypeOf(T), 122, codec.NewSelfBytesExt(msgpackHandle, 1024))
 //
-// This extension expects that types registered with it implement SelfExt interface.
-var GlobalSelfInterfaceExt InterfaceExt = selfInterfaceExt{}
-
-// var selfExtEncPool = sync.Pool{
-// 	New: func() interface{} { return new(Encoder) },
-// }
-// var selfExtDecPool = sync.Pool{
-// 	New: func() interface{} { return new(Decoder) },
-// }
-
-// SelfExt is the interface that users implement so that their types
-// can, with minimal effort, be able to be an extension while allowing the
-// library handling the encoding/decoding needs easily.
 type SelfExt interface {
 	CodecConvertExt() interface{}
 	CodecUpdateExt(interface{})
 }
 
 type selfBytesExt struct {
+	// For performance and memory utilization, use sync.Pools
+	// They all have to be local to the Ext, as the Ext is bound to a Handle.
 	p sync.Pool // pool of byte buffers
 	e sync.Pool
 	d sync.Pool
 	h Handle
 	// bufcap int     // cap for each byte buffer created
-	// inited uint32
-	// mu sync.Mutex
 }
 
 type selfInterfaceExt struct{}
 
 // NewSelfBytesExt will return a BytesExt implementation,
 // that will call an encoder to encode the value to a stream
-// so it can be placed into the encoder stream.
+// so it can be placed into the encoder stream, and use a decoder
+// to do the same on the other end.
 //
 // Users can specify a buffer size, and we will initialize that
 // buffer for encoding the type. This allows users manage
 // how big the buffer is based on their knowledge of the type being
 // registered.
 //
-// This extension expects that types registered with it implement
-// SelfExt interface.
+// This extension expects that types registered with it implement SelfExt interface.
 //
 // This is used by libraries that support BytesExt e.g. msgpack, binc.
 func NewSelfBytesExt(h Handle, bufcap int) *selfBytesExt {