GODRIVER-904 Improve documentation for registering custom codecs (#276)

Author: Divjot Arora

bson/bsoncodec/doc.go

@@ -27,28 +27,51 @@
 //
 // Registry and RegistryBuilder
 //
-// A Registry is an immutable store for ValueEncoders, ValueDecoders, and a type map. For looking up
-// ValueEncoders and Decoders the Registry first attempts to find a ValueEncoder or ValueDecoder for
-// the type provided; if one cannot be found it then checks to see if a registered ValueEncoder or
-// ValueDecoder exists for an interface the type implements. Finally, the reflect.Kind of the type
-// is used to lookup a default ValueEncoder or ValueDecoder for that kind. If no ValueEncoder or
-// ValueDecoder can be found, an error is returned.
-//
-// The Registry also holds a type map. This allows users to retrieve the Go type that should be used
-// when decoding a BSON value into an empty interface. This is primarily only used for the empty
-// interface ValueDecoder.
-//
-// A RegistryBuilder is used to construct a Registry. The Register methods are used to associate
-// either a reflect.Type or a reflect.Kind with a ValueEncoder or ValueDecoder. A RegistryBuilder
-// returned from NewRegistryBuilder contains no registered ValueEncoders nor ValueDecoders and
-// contains an empty type map.
-//
-// The RegisterTypeMapEntry method handles associating a BSON type with a Go type. For example, if
-// you want to decode BSON int64 and int32 values into Go int instances, you would do the following:
-//
-//  var regbuilder *RegistryBuilder = ... intType := reflect.TypeOf(int(0))
-//  regbuilder.RegisterTypeMapEntry(bsontype.Int64, intType).RegisterTypeMapEntry(bsontype.Int32,
-//  intType)
+// A Registry is an immutable store for ValueEncoders, ValueDecoders, and a type map. See the Registry type
+// documentation for examples of registering various custom encoders and decoders. A Registry can be constructed using a
+// RegistryBuilder, which handles three main types of codecs:
+//
+// 1. Type encoders/decoders - These can be registered using the RegisterTypeEncoder and RegisterTypeDecoder methods.
+// The registered codec will be invoked when encoding/decoding a value whose type matches the registered type exactly.
+// If the registered type is an interface, the codec will be invoked when encoding or decoding values whose type is the
+// interface, but not for values with concrete types that implement the interface.
+//
+// 2. Hook encoders/decoders - These can be registered using the RegisterHookEncoder and RegisterHookDecoder methods.
+// These methods only accept interface types and the registered codecs will be invoked when encoding or decoding values
+// whose types implement the interface. An example of a hook defined by the driver is bson.Marshaler. The driver will
+// call the MarshalBSON method for any value whose type implements bson.Marshaler, regardless of the value's concrete
+// type.
+//
+// 3. Type map entries - This can be used to associate a BSON type with a Go type. These type associations are used when
+// decoding into a bson.D/bson.M or a struct field of type interface{}. For example, by default, BSON int32 and int64
+// values decode as Go int32 and int64 instances, respectively, when decoding into a bson.D. The following code would
+// change the behavior so these values decode as Go int instances instead:
+//
+//		intType := reflect.TypeOf(int(0))
+//		registryBuilder.RegisterTypeMapEntry(bsontype.Int32, intType).RegisterTypeMapEntry(bsontype.Int64, intType)
+//
+// 4. Kind encoder/decoders - These can be registered using the RegisterDefaultEncoder and RegisterDefaultDecoder
+// methods. The registered codec will be invoked when encoding or decoding values whose reflect.Kind matches the
+// registered reflect.Kind as long as the value's type doesn't match a registered type or hook encoder/decoder first.
+// These methods should be used to change the behavior for all values for a specific kind.
+//
+// Registry Lookup Procedure
+//
+// When looking up an encoder in a Registry, the precedence rules are as follows:
+//
+// 1. A type encoder registered for the exact type of the value.
+//
+// 2. A hook encoder registered for an interface that is implemented by the value or by a pointer to the value. If the
+// value matches multiple hooks (e.g. the type implements bsoncodec.Marshaler and bsoncodec.ValueMarshaler), the first
+// one registered will be selected. Note that registries constructed using bson.NewRegistryBuilder have driver-defined
+// hooks registered for the bsoncodec.Marshaler, bsoncodec.ValueMarshaler, and bsoncodec.Proxy interfaces, so those
+// will take precedence over any new hooks.
+//
+// 3. A kind encoder registered for the value's kind.
+//
+// If all of these lookups fail to find an encoder, an error of type ErrNoEncoder is returned. The same precedence
+// rules apply for decoders, with the exception that an error of type ErrNoDecoder will be returned if no decoder is
+// found.
 //
 // DefaultValueEncoders and DefaultValueDecoders
 //

bson/bsoncodec/registry_examples_test.go

@@ -0,0 +1,111 @@
+// Copyright (C) MongoDB, Inc. 2017-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// 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 bsoncodec_test
+
+import (
+	"fmt"
+	"math"
+	"reflect"
+
+	"go.mongodb.org/mongo-driver/bson/bsoncodec"
+	"go.mongodb.org/mongo-driver/bson/bsonrw"
+	"go.mongodb.org/mongo-driver/bson/bsontype"
+)
+
+func ExampleRegistry_customEncoder() {
+	// Write a custom encoder for an integer type that is multiplied by -1 when encoding.
+
+	// To register the default encoders and decoders in addition to this custom one, use bson.NewRegistryBuilder
+	// instead.
+	rb := bsoncodec.NewRegistryBuilder()
+	type negatedInt int
+
+	niType := reflect.TypeOf(negatedInt(0))
+	encoder := func(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error {
+		// All encoder implementations should check that val is valid and is of the correct type before proceeding.
+		if !val.IsValid() || val.Type() != niType {
+			return bsoncodec.ValueEncoderError{
+				Name:     "negatedIntEncodeValue",
+				Types:    []reflect.Type{niType},
+				Received: val,
+			}
+		}
+
+		// Negate val and encode as a BSON int32 if it can fit in 32 bits and a BSON int64 otherwise.
+		negatedVal := val.Int() * -1
+		if math.MinInt32 <= negatedVal && negatedVal <= math.MaxInt32 {
+			return vw.WriteInt32(int32(negatedVal))
+		}
+		return vw.WriteInt64(negatedVal)
+	}
+
+	rb.RegisterTypeEncoder(niType, bsoncodec.ValueEncoderFunc(encoder))
+}
+
+func ExampleRegistry_customDecoder() {
+	// Write a custom decoder for a boolean type that can be stored in the database as a BSON boolean, int32, int64,
+	// double, or null. BSON int32, int64, and double values are considered "true" in this decoder if they are
+	// non-zero. BSON null values are always considered false.
+
+	// To register the default encoders and decoders in addition to this custom one, use bson.NewRegistryBuilder
+	// instead.
+	rb := bsoncodec.NewRegistryBuilder()
+	type lenientBool bool
+
+	decoder := func(dc bsoncodec.DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error {
+		// All decoder implementations should check that val is valid and settable and is of the correct kind
+		// before proceeding.
+		if !val.IsValid() || !val.CanSet() || val.Kind() != reflect.Bool {
+			return bsoncodec.ValueDecoderError{
+				Name:     "lenientBoolDecodeValue",
+				Kinds:    []reflect.Kind{reflect.Bool},
+				Received: val,
+			}
+		}
+
+		var result bool
+		switch vr.Type() {
+		case bsontype.Boolean:
+			b, err := vr.ReadBoolean()
+			if err != nil {
+				return err
+			}
+			result = b
+		case bsontype.Int32:
+			i32, err := vr.ReadInt32()
+			if err != nil {
+				return err
+			}
+			result = i32 != 0
+		case bsontype.Int64:
+			i64, err := vr.ReadInt64()
+			if err != nil {
+				return err
+			}
+			result = i64 != 0
+		case bsontype.Double:
+			f64, err := vr.ReadDouble()
+			if err != nil {
+				return err
+			}
+			result = f64 != 0
+		case bsontype.Null:
+			if err := vr.ReadNull(); err != nil {
+				return err
+			}
+			result = false
+		default:
+			return fmt.Errorf("received invalid BSON type to decode into lenientBool: %s", vr.Type())
+		}
+
+		val.SetBool(result)
+		return nil
+	}
+
+	lbType := reflect.TypeOf(lenientBool(true))
+	rb.RegisterTypeDecoder(lbType, bsoncodec.ValueDecoderFunc(decoder))
+}

bson/doc.go

@@ -6,6 +6,8 @@
 
 // Package bson is a library for reading, writing, and manipulating BSON. BSON is a binary serialization format used to
 // store documents and make remote procedure calls in MongoDB. The BSON specification is located at https://bsonspec.org.
+// The BSON library handles marshalling and unmarshalling of values through a configurable codec system. For a description
+// of the codec system and examples of registering custom codecs, see the bsoncodec package.
 //
 // Raw BSON
 //
@@ -90,7 +92,7 @@
 //     1. omitempty: If the omitempty struct tag is specified on a field, the field will not be marshalled if it is set to
 //     the zero value. By default, a struct field is only considered empty if the field's type implements the Zeroer
 //     interface and the IsZero method returns true. Struct fields of types that do not implement Zeroer are always
-//     marshalled as embedded documents.
+//     marshalled as embedded documents. This tag should be used for all slice and map values.
 //
 //     2. minsize: If the minsize struct tag is specified on a field of type int64, uint, uint32, or uint64 and the value of
 //     the field can fit in a signed int32, the field will be serialized as a BSON int32 rather than a BSON int64. For other