GODRIVER-242 Document the valid struct tags for bson.Encoder and bson.Decoder

Change-Id: Ib33a1ea80a5d68d0299b0bc82b081b9956bbc264

Author: saghm

bson/decode.go

@@ -125,8 +125,24 @@ func NewDecoder(r io.Reader) *Decoder {
 //   - any map with string keys
 //   - a struct (possibly with tags)
 //
-// In the case of a map or struct, Decode will treat the value as a BSON document with the map keys
-// or struct field names as the keys and the map values or struct fields as the values.
+// In the case of struct values, only exported fields will be deserialized. The lowercased field
+// name is used as the key for each exported field, but this behavior may be changed using a struct
+// tag. The tag may also contain flags to adjust the unmarshaling behavior for the field. The tag
+// formats accepted are:
+//
+//     "[<key>][,<flag1>[,<flag2>]]"
+//
+//     `(...) bson:"[<key>][,<flag1>[,<flag2>]]" (...)`
+//
+// The target field or element types of out may not necessarily match the BSON values of the
+// provided data. The following conversions are made automatically:
+//
+//   - Numeric types are converted if at least the integer part of the value would be preserved
+//     correctly
+//
+// If the value would not fit the type and cannot be converted, it is silently skipped.
+//
+// Pointer values are initialized when necessary.
 func (d *Decoder) Decode(v interface{}) error {
 	switch t := v.(type) {
 	case Unmarshaler:

bson/encode.go

@@ -56,8 +56,35 @@ type Encoder interface {
 	//   - any map with string keys
 	//   - a struct (possibly with tags)
 	//
-	// In the case of a map or struct, Encode will interpret the value as a BSON document with the map
-	// keys or struct field names as the keys and the map values or struct fields as the values.
+	// In the case of a struct, the lowercased field name is used as the key for each exported
+	// field but this behavior may be changed using a struct tag. The tag may also contain flags to
+	// adjust the marshalling behavior for the field. The tag formats accepted are:
+	//
+	//     "[<key>][,<flag1>[,<flag2>]]"
+	//
+	//     `(...) bson:"[<key>][,<flag1>[,<flag2>]]" (...)`
+	//
+	// The following flags are currently supported:
+	//
+	//     omitempty  Only include the field if it's not set to the zero value for the type or to
+	//                empty slices or maps.
+	//
+	//     minsize    Marshal an integer of a type larger than 32 bits value as an int32, if that's
+	//                feasible while preserving the numeric value.
+	//
+	//     inline     Inline the field, which must be a struct or a map, causing all of its fields
+	//                or keys to be processed as if they were part of the outer struct.
+	//
+	// An example:
+	//
+	//     type T struct {
+	//         A bool
+	//         B int    "myb"
+	//         C string "myc,omitempty"
+	//         D string `bson:",omitempty" json:"jsonkey"`
+	//         E int64  ",minsize"
+	//         F int64  "myf,omitempty,minsize"
+	//     }
 	Encode(interface{}) error
 }
 

bson/marshal.go

@@ -10,7 +10,45 @@ import "bytes"
 
 // Marshal converts a BSON type to bytes.
 //
-// TODO(GODRIVER-257): Document which types are valid for value.
+// The value can be any one of the following types:
+//
+//   - bson.Marshaler
+//   - io.Reader
+//   - []byte
+//   - bson.Reader
+//   - any map with string keys
+//   - a struct (possibly with tags)
+//
+// In the case of a struct, the lowercased field name is used as the key for each exported
+// field but this behavior may be changed using a struct tag. The tag may also contain flags to
+// adjust the marshalling behavior for the field. The tag formats accepted are:
+//
+//     "[<key>][,<flag1>[,<flag2>]]"
+//
+//     `(...) bson:"[<key>][,<flag1>[,<flag2>]]" (...)`
+//
+// The following flags are currently supported:
+//
+//     omitempty  Only include the field if it's not set to the zero value for the type or to
+//                empty slices or maps.
+//
+//     minsize    Marshal an integer of a type larger than 32 bits value as an int32, if that's
+// 				  feasible while preserving the numeric value.
+//
+//     inline     Inline the field, which must be a struct or a map, causing all of its fields
+//                or keys to be processed as if they were part of the outer struct. For maps,
+//                keys must not conflict with the bson keys of other struct fields.
+//
+// An example:
+//
+//     type T struct {
+//         A bool
+//         B int    "myb"
+//         C string "myc,omitempty"
+//         D string `bson:",omitempty" json:"jsonkey"`
+//         E int64  ",minsize"
+//         F int64  "myf,omitempty,minsize"
+//     }
 func Marshal(value interface{}) ([]byte, error) {
 	var out bytes.Buffer
 
@@ -24,7 +62,33 @@ func Marshal(value interface{}) ([]byte, error) {
 
 // Unmarshal converts bytes into a BSON type.
 //
-// TODO(GODRIVER-257): Document which types are valid for value.
+// The value can be any one of the following types:
+//
+//   - bson.Unmarshaler
+//   - io.Writer
+//   - []byte
+//   - bson.Reader
+//   - any map with string keys
+//   - a struct (possibly with tags)
+//
+// In the case of struct values, only exported fields will be deserialized. The lowercased field
+// name is used as the key for each exported field, but this behavior may be changed using a struct
+// tag. The tag may also contain flags to adjust the unmarshaling behavior for the field. The tag
+// formats accepted are:
+//
+//     "[<key>][,<flag1>[,<flag2>]]"
+//
+//     `(...) bson:"[<key>][,<flag1>[,<flag2>]]" (...)`
+//
+// The target field or element types of out may not necessarily match the BSON values of the
+// provided data. The following conversions are made automatically:
+//
+//   - Numeric types are converted if at least the integer part of the value would be preserved
+//     correctly
+//
+// If the value would not fit the type and cannot be converted, it is silently skipped.
+//
+// Pointer values are initialized when necessary.
 func Unmarshal(in []byte, out interface{}) error {
 	return NewDecoder(bytes.NewReader(in)).Decode(out)
 }