Update documentation for stable BSON packages

Change-Id: I2df9c682d0e1237999417216464c785cb54b89a8

Author: skriptble

bson/bson.go

@@ -15,17 +15,6 @@ import (
 	"strings"
 )
 
-// node is a compact representation of an element within a BSON document.
-// The first 4 bytes are where the element starts in an underlying []byte. The
-// last 4 bytes are where the value for that element begins.
-//
-// The type of the element can be accessed as `data[n[0]]`. The key of the
-// element can be accessed as `data[n[0]+1:n[1]-1]`. This will account for the
-// null byte at the end of the c-style string. The value can be accessed as
-// `data[n[1]:]`. Since there is no value end byte, an unvalidated document
-// could result in parsing errors.
-type node [2]uint32
-
 // Zeroer allows custom struct types to implement a report of zero
 // state. All struct types that don't implement Zeroer or where IsZero
 // returns false are considered to be not zero.

bson/decimal/decimal.go

@@ -7,6 +7,7 @@
 // Based on gopkg.in/mgo.v2/bson by Gustavo Niemeyer
 // See THIRD-PARTY-NOTICES for original license terms.
 
+// Package decimal implements a Decimal128 type.
 package decimal
 
 import (

bson/decoder.go

@@ -25,7 +25,8 @@ var decPool = sync.Pool{
 	},
 }
 
-// A Decoder reads and decodes BSON documents from a stream.
+// A Decoder reads and decodes BSON documents from a stream. It reads from a bsonrw.ValueReader as
+// the source of BSON data.
 type Decoder struct {
 	r  *bsoncodec.Registry
 	vr bsonrw.ValueReader

bson/doc.go

@@ -5,37 +5,38 @@
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
 // Package bson is a library for reading, writing, and manipulating BSON. The
-// library has three types for representing BSON.
-//
-// The Reader type is used to validate and retrieve elements from a byte slice.
-// If you are not manipulating the underlying document and just want to validate
-// or ensure the document has certain keys, this is the type you should use.
-//
-// The Document type is a more generic type that can do all the read actions the
-// Reader can do and allows for manipulation of documents. The main usecase for
-// this type is reading some BSON and then adding, changing, or removing
-// elements or to build a document that will need to be manipulated later. If
-// the document can be created in a single pass without the need to do any
-// lookups, the Builder type is might be more appropriate.
-//
-// The Builder type (in the "bson/builder" package) is used to create a BSON
-// document. The type only allows the iterative building of a document, so there
-// is no way to verify the contents outside of writing the document. If you have
-// a Builder and need to conditionally add a field, you can write the document
-// to a byte slice and use the Reader type to lookup the desired document, but
-// in this case you should probably use a Document instead.
-//
-// The Element type represents a BSON element and the Value type represents an
-// individual value for a BSON element.
-//
-// The Encoder and Decoder types can be used to marshal a type to an io.Writer
-// or to unmarshal into a type from an io.Reader. These types will use
-// reflection and evaluate struct tags unless the provided types implements the
-// Marshaler or Unmarshaler interfaces. The Builder and Reader types can be used
-// to implement these interfaces for types.
-//
-// The DocumentEncoder type can be used to encode a type to a Document instead
-// of an io.Writer. This is useful if some additional manipulation is required
-// after encoding a document. This type supports the same encoding behavior as
-// the Encoder type.
+// library has two families of types for representing BSON.
+//
+// The Raw family of types is used to validate and retrieve elements from a slice of bytes. This
+// type is most useful when you want do lookups on BSON bytes without unmarshaling it into another
+// type.
+//
+// Example:
+// 		var raw bson.Raw = ... // bytes from somewhere
+// 		err := raw.Validate()
+// 		if err != nil { return err }
+// 		val := raw.Lookup("foo")
+// 		i32, ok := val.Int32OK()
+// 		// do something with i32...
+//
+// The D family of types is used to build concise representations of BSON using native Go types.
+// These types do not support automatic lookup.
+//
+// Example:
+// 		bson.D{{"foo", "bar"}, {"hello", "world"}, {"pi", 3.14159}}
+//
+//
+// Marshaling and Unmarshaling are handled with the Marshal and Unmarshal family of functions. If
+// you need to write or read BSON from a non-slice source, an Encoder or Decoder can be used with a
+// bsonrw.ValueWriter or bsonrw.ValueReader.
+//
+// Example:
+// 		b, err := bson.Marshal(bson.D{{"foo", "bar"}})
+// 		if err != nil { return err }
+// 		var fooer struct {
+// 			Foo string
+// 		}
+// 		err = bson.Unmarshal(b, &fooer)
+// 		if err != nil { return err }
+// 		// do something with fooer...
 package bson

bson/encoder.go

@@ -24,7 +24,8 @@ var encPool = sync.Pool{
 	},
 }
 
-// An Encoder writes a serialization format to an output stream.
+// An Encoder writes a serialization format to an output stream. It writes to a bsonrw.ValueWriter
+// as the destination of BSON data.
 type Encoder struct {
 	r  *bsoncodec.Registry
 	vw bsonrw.ValueWriter

bson/objectid/objectid.go

@@ -7,6 +7,8 @@
 // Based on gopkg.in/mgo.v2/bson by Gustavo Niemeyer
 // See THIRD-PARTY-NOTICES for original license terms.
 
+// Package objectid contains an implementation of a BSON objectID type functions to create
+// objectIDs.
 package objectid
 
 import (

bson/primitive/primitive.go

@@ -4,6 +4,8 @@
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 
+// Package primitive contains types similar to Go primitives for BSON types can do not have direct
+// Go primitive representations.
 package primitive
 
 import (

bson/raw.go

@@ -18,7 +18,8 @@ var ErrNilReader = errors.New("nil reader")
 var errValidateDone = errors.New("validation loop complete")
 
 // Raw is a wrapper around a byte slice. It will interpret the slice as a
-// BSON document. This type is a wrapper around a bsoncore.Document.
+// BSON document. This type is a wrapper around a bsoncore.Document. Errors returned from the
+// methods on this type and associated types come from the bsoncore package.
 type Raw []byte
 
 // NewFromIOReader reads in a document from the given io.Reader and constructs a Raw from
@@ -36,11 +37,6 @@ func (r Raw) Validate() (err error) { return bsoncore.Document(r).Validate() }
 // there are multiple keys provided, this method will recurse down, as long as
 // the top and intermediate nodes are either documents or arrays. If any key
 // except for the last is not a document or an array, an error will be returned.
-//
-// TODO(skriptble): Implement better error messages.
-//
-// TODO(skriptble): Determine if this should return an error on empty key and
-// key not found.
 func (r Raw) Lookup(key ...string) RawValue {
 	return convertFromCoreValue(bsoncore.Document(r).Lookup(key...))
 }

bson/raw_element.go

@@ -10,17 +10,6 @@ import (
 	"github.com/mongodb/mongo-go-driver/x/bsonx/bsoncore"
 )
 
-// MalformedElementError represents a class of errors that RawElement methods return.
-type MalformedElementError string
-
-func (mee MalformedElementError) Error() string { return string(mee) }
-
-// ErrElementMissingKey is returned when a RawElement is missing a key.
-const ErrElementMissingKey MalformedElementError = "element is missing key"
-
-// ErrElementMissingType is returned when a RawElement is missing a type.
-const ErrElementMissingType MalformedElementError = "element is missing type"
-
 // RawElement represents a BSON element in byte form. This type provides a simple way to
 // transform a slice of bytes into a BSON element and extract information from it.
 //