GODRIVER-1061 Remove references to RawArray and Array types in BSON docs (#248)

Author: Divjot Arora

bson/bson.go

@@ -22,39 +22,29 @@ type Zeroer interface {
 	IsZero() bool
 }
 
-// D represents a BSON Document. This type can be used to represent BSON in a concise and readable
-// manner. It should generally be used when serializing to BSON. For deserializing, the Raw or
-// Document types should be used.
+// D is an ordered representation of a BSON document. This type should be used when the order of the elements matters,
+// such as MongoDB command documents. If the order of the elements does not matter, an M should be used instead.
 //
 // Example usage:
 //
 // 		bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}}
-//
-// This type should be used in situations where order matters, such as MongoDB commands. If the
-// order is not important, a map is more comfortable and concise.
 type D = primitive.D
 
 // E represents a BSON element for a D. It is usually used inside a D.
 type E = primitive.E
 
-// M is an unordered, concise representation of a BSON Document. It should generally be used to
-// serialize BSON when the order of the elements of a BSON document do not matter. If the element
-// order matters, use a D instead.
+// M is an unordered representation of a BSON document. This type should be used when the order of the elements does not
+// matter. This type is handled as a regular map[string]interface{} when encoding and decoding. Elements will be
+// serialized in an undefined, random order. If the order of the elements matters, a D should be used instead.
 //
 // Example usage:
 //
 // 		bson.M{"foo": "bar", "hello": "world", "pi": 3.14159}
-//
-// This type is handled in the encoders as a regular map[string]interface{}. The elements will be
-// serialized in an undefined, random order, and the order will be different each time.
 type M = primitive.M
 
-// An A represents a BSON array. This type can be used to represent a BSON array in a concise and
-// readable manner. It should generally be used when serializing to BSON. For deserializing, the
-// RawArray or Array types should be used.
+// An A is an ordered representation of a BSON array.
 //
 // Example usage:
 //
 // 		bson.A{"bar", "world", 3.14159, bson.D{{"qux", 12345}}}
-//
 type A = primitive.A

bson/bson_1_8.go

@@ -21,16 +21,12 @@ type Zeroer interface {
 	IsZero() bool
 }
 
-// D represents a BSON Document. This type can be used to represent BSON in a concise and readable
-// manner. It should generally be used when serializing to BSON. For deserializing, the Raw or
-// Document types should be used.
+// D is an ordered representation of a BSON document. This type should be used when the order of the elements matters,
+// such as MongoDB command documents. If the order of the elements does not matter, an M should be used instead.
 //
 // Example usage:
 //
-// 		primitive.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}}
-//
-// This type should be used in situations where order matters, such as MongoDB commands. If the
-// order is not important, a map is more comfortable and concise.
+// 		bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}}
 type D []E
 
 // Map creates a map from the elements of the D.
@@ -48,26 +44,20 @@ type E struct {
 	Value interface{}
 }
 
-// M is an unordered, concise representation of a BSON Document. It should generally be used to
-// serialize BSON when the order of the elements of a BSON document do not matter. If the element
-// order matters, use a D instead.
+// M is an unordered representation of a BSON document. This type should be used when the order of the elements does not
+// matter. This type is handled as a regular map[string]interface{} when encoding and decoding. Elements will be
+// serialized in an undefined, random order. If the order of the elements matters, a D should be used instead.
 //
 // Example usage:
 //
-// 		primitive.M{"foo": "bar", "hello": "world", "pi": 3.14159}
-//
-// This type is handled in the encoders as a regular map[string]interface{}. The elements will be
-// serialized in an undefined, random order, and the order will be different each time.
+// 		bson.M{"foo": "bar", "hello": "world", "pi": 3.14159}
 type M map[string]interface{}
 
-// An A represents a BSON array. This type can be used to represent a BSON array in a concise and
-// readable manner. It should generally be used when serializing to BSON. For deserializing, the
-// RawArray or Array types should be used.
+// An A is an ordered representation of a BSON array.
 //
 // Example usage:
 //
-// 		primitive.A{"bar", "world", 3.14159, primitive.D{{"qux", 12345}}}
-//
+// 		bson.A{"bar", "world", 3.14159, bson.D{{"qux", 12345}}}
 type A []interface{}
 
 func formatDouble(f float64) string {

bson/primitive/primitive.go

@@ -156,16 +156,12 @@ type MinKey struct{}
 // MaxKey represents the BSON maxkey value.
 type MaxKey struct{}
 
-// D represents a BSON Document. This type can be used to represent BSON in a concise and readable
-// manner. It should generally be used when serializing to BSON. For deserializing, the Raw or
-// Document types should be used.
+// D is an ordered representation of a BSON document. This type should be used when the order of the elements matters,
+// such as MongoDB command documents. If the order of the elements does not matter, an M should be used instead.
 //
 // Example usage:
 //
-// 		primitive.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}}
-//
-// This type should be used in situations where order matters, such as MongoDB commands. If the
-// order is not important, a map is more comfortable and concise.
+// 		bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}}
 type D []E
 
 // Map creates a map from the elements of the D.
@@ -183,24 +179,18 @@ type E struct {
 	Value interface{}
 }
 
-// M is an unordered, concise representation of a BSON Document. It should generally be used to
-// serialize BSON when the order of the elements of a BSON document do not matter. If the element
-// order matters, use a D instead.
+// M is an unordered representation of a BSON document. This type should be used when the order of the elements does not
+// matter. This type is handled as a regular map[string]interface{} when encoding and decoding. Elements will be
+// serialized in an undefined, random order. If the order of the elements matters, a D should be used instead.
 //
 // Example usage:
 //
-// 		primitive.M{"foo": "bar", "hello": "world", "pi": 3.14159}
-//
-// This type is handled in the encoders as a regular map[string]interface{}. The elements will be
-// serialized in an undefined, random order, and the order will be different each time.
+// 		bson.M{"foo": "bar", "hello": "world", "pi": 3.14159}.
 type M map[string]interface{}
 
-// An A represents a BSON array. This type can be used to represent a BSON array in a concise and
-// readable manner. It should generally be used when serializing to BSON. For deserializing, the
-// RawArray or Array types should be used.
+// An A is an ordered representation of a BSON array.
 //
 // Example usage:
 //
-// 		primitive.A{"bar", "world", 3.14159, primitive.D{{"qux", 12345}}}
-//
+// 		bson.A{"bar", "world", 3.14159, bson.D{{"qux", 12345}}}
 type A []interface{}