data: more doc comments; IsDefined rename for CIDLink

atproto/data/blob.go

···
 	cbg "github.com/whyrusleeping/cbor-gen"
 )
 
-// used in schemas, and can represent either a legacy blob or a "new" (lex
-// refactor) blob. size=-1 indicates that this is (and should be serialized as)
-// a legacy blob (string CID, no size, etc).
+// Represents the "blob" type from the atproto data model.
+//
+// This struct does not get marshaled/unmarshaled directly in to JSON or CBOR; see the BlobSchema and LegacyBlobSchema structs. This is the type that should be included in golang struct definitions.
+//
+// When representing a "legacy" blob (no size field, string CID), size == -1.
 type Blob struct {
 	Ref      CIDLink
 	MimeType string

atproto/data/bytes.go

···
 	cbg "github.com/whyrusleeping/cbor-gen"
 )
 
+// Represents the "bytes" type from the atproto data model.
+//
+// In JSON, marshals to an object with $bytes key and base64-encoded data.
+//
+// In CBOR, marshals to a byte array.
 type Bytes []byte
 
 type JsonBytes struct {

atproto/data/cidlink.go

···
 	cbg "github.com/whyrusleeping/cbor-gen"
 )
 
+// Represents the "cid-link" type from the atproto data model.
+//
+// Implementation is a simple wrapper around the github.com/ipfs/go-cid "cid.Cid" type.
 type CIDLink cid.Cid
 
 type jsonLink struct {
 	Link string `json:"$link"`
 }
 
-// convenience helper
+// Unwraps the inner cid.Cid type (github.com/ipfs/go-cid)
+func (ll CIDLink) CID() cid.Cid {
+	return cid.Cid(ll)
+}
+
+// Returns string representation.
+//
+// If the CID is "undefined", returns an empty string (note that this is different from how cid.Cid works).
 func (ll CIDLink) String() string {
-	return cid.Cid(ll).String()
+	if ll.IsDefined() {
+		return cid.Cid(ll).String()
+	}
+	return ""
 }
 
-// convenience helper
-func (ll CIDLink) Defined() bool {
+// Convenience helper, returns false if CID is "undefined" (golang zero value)
+func (ll CIDLink) IsDefined() bool {
 	return cid.Cid(ll).Defined()
 }
 
 func (ll CIDLink) MarshalJSON() ([]byte, error) {
-	if !ll.Defined() {
+	if !ll.IsDefined() {
 		return nil, fmt.Errorf("tried to marshal nil or undefined cid-link")
 	}
 	jl := jsonLink{
···
 		_, err := w.Write(cbg.CborNull)
 		return err
 	}
-	if !ll.Defined() {
+	if !ll.IsDefined() {
 		return fmt.Errorf("tried to marshal nil or undefined cid-link")
 	}
 	cw := cbg.NewCborWriter(w)

atproto/data/const.go

···
 package data
 
 const (
-	MAX_OBJECT_KEY_LEN        = 8192
-	MAX_CBOR_SIZE             = 5 * 1024 * 1024
-	MAX_CBOR_RECORD_SIZE      = 1 * 1024 * 1024
-	MAX_JSON_RECORD_SIZE      = 2 * 1024 * 1024
+	// maximum size of any CBOR data, in any context, in atproto
+	MAX_CBOR_SIZE = 5 * 1024 * 1024
+	// maximum serialized size of an individual atproto record, in CBOR format
+	MAX_CBOR_RECORD_SIZE = 1 * 1024 * 1024
+	// maximum serialized size of an individual atproto record, in JSON format
+	MAX_JSON_RECORD_SIZE = 2 * 1024 * 1024
+	// maximum serialized size of blocks (raw bytes) in an atproto repo stream event
 	MAX_STREAM_REPO_DIFF_SIZE = 4 * 1024 * 1024
-	MAX_STREAM_FRAME_SIZE     = MAX_CBOR_SIZE
-	MAX_RECORD_STRING_LEN     = MAX_CBOR_RECORD_SIZE
-	MAX_RECORD_BYTES_LEN      = MAX_CBOR_RECORD_SIZE
-	MAX_CID_BYTES             = 100
-	MAX_CBOR_NESTED_LEVELS    = 32
-	MAX_CBOR_CONTAINER_LEN    = 128 * 1024
-	MAX_SAFE_INTEGER          = 9007199254740991
-	MIN_SAFE_INTEGER          = -9007199254740991
+	// maximum size of a WebSocket frame in atproto event streams
+	MAX_STREAM_FRAME_SIZE = MAX_CBOR_SIZE
+	// maximum size of any individual string inside an atproto record
+	MAX_RECORD_STRING_LEN = MAX_CBOR_RECORD_SIZE
+	// maximum size of any individual byte array (bytestring) inside an atproto record
+	MAX_RECORD_BYTES_LEN = MAX_CBOR_RECORD_SIZE
+	// limit on size of CID representation
+	MAX_CID_BYTES = 100
+	// limit on depth of nested containers (objects or arrays) for atproto data
+	MAX_CBOR_NESTED_LEVELS = 32
+	// maximum number of elements in an object or array in atproto data
+	MAX_CBOR_CONTAINER_LEN = 128 * 1024
+	// largest integer which can be represented in a float64. integers in atproto "should" not be larger than this.
+	MAX_SAFE_INTEGER = 9007199254740991
+	// largest negative integer which can be represented in a float64. integers in atproto "should" not go below this.
+	MIN_SAFE_INTEGER = -9007199254740991
+	// maximum length of string (UTF-8 bytes) in an atproto object (map)
+	MAX_OBJECT_KEY_LEN = 8192
 )