js feedback

Author: mongoKart

source/data-formats/custom-types.txt

@@ -40,7 +40,7 @@ to save an instance of ``Decimal`` with {+driver-short+} results in an
       from decimal import Decimal
 
       num = Decimal("45.321")
-      db.coll.insert_one({"num": num})
+      db["coll"].insert_one({"num": num})
 
    .. output::
       :language: shell
@@ -56,8 +56,8 @@ Define a Type Codec Class
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To encode a custom type, you must first define a **type codec.** A type codec
-describes how an instance of a custom type can be
-converted to and from one of the types the ``bson`` module can already encode.
+describes how an instance of a custom type is
+converted to and from a type that the ``bson`` module can already encode.
 
 When you define a type codec, your class must inherit from one of the base classes in the
 ``codec_options`` module. The following table describes these base classes, and when
@@ -75,30 +75,30 @@ and how to implement them:
    * - ``codec_options.TypeEncoder``
      - Inherit from this class to define a codec that
        encodes a custom Python type to a known BSON type.
-     - - ``python_type`` attribute: The Python type acted on by this type codec
+     - - ``python_type`` attribute: The custom Python type that's encoded by this type codec
        - ``transform_python()`` method: Function that transforms a custom type value into a type
          that BSON can encode
 
    * - ``codec_options.TypeDecoder``
      - Inherit from this class to define a codec that
        decodes a specified BSON type into a custom Python type.
-     - - ``bson_type`` attribute: The BSON type acted on by this type codec
+     - - ``bson_type`` attribute: The BSON type that's decoded by this type codec
        - ``transform_bson()`` method: Function that transforms a standard BSON type value
          into the custom type
 
    * - ``codec_options.TypeCodec``
      - Inherit from this class to define a codec that
        can both encode and decode a custom type.
-     - - ``python_type`` attribute: The Python type acted on by this type codec
-       - ``bson_type`` attribute: The BSON type acted on by this type codec
+     - - ``python_type`` attribute: The custom Python type that's encoded by this type codec
+       - ``bson_type`` attribute: The BSON type that's decoded by this type codec
        - ``transform_bson()`` method: Function that transforms a standard BSON type value
          into the custom type
        - ``transform_python()`` method: Function that transforms a custom type value into a type
          that BSON can encode
 
 Because the example ``Decimal`` custom type can be converted to and from a
 ``Decimal128`` instance, you must define how to encode and decode this type.
-Therefore, the``Decimal`` type codec class must inherit from
+Therefore, the ``Decimal`` type codec class must inherit from
 the ``TypeCodec`` base class:
 
 .. code-block:: python
@@ -125,6 +125,9 @@ To do so, create an instance of the ``TypeRegistry`` class, passing in an instan
 of your type codec class inside a list. If you create multiple custom codecs, you can
 pass them all to the ``TypeRegistry`` constructor.
 
+The following code examples adds an instance of the ``DecimalCodec`` type codec to
+the type registry:
+
 .. code-block:: python
 
    from bson.codec_options import TypeRegistry
@@ -196,8 +199,8 @@ Encode a Subtype
 ----------------
 
 You might also need to encode one or more types that inherit from your custom type.
-Consider this subtype of the ``Decimal`` type, which contains a method to return its value
-as an integer:
+Consider the following subtype of the ``Decimal`` class, which contains a method to
+return its value as an integer:
 
 .. code-block:: python
 
@@ -225,14 +228,15 @@ codec for it, {+driver-short+} raises an error:
       of type: <class 'decimal.Decimal'>
 
 To encode an instance of the ``DecimalInt`` class, you must define a type codec for
-the class. This type codec must inherit from the parent class's codec:
+the class. This type codec must inherit from the parent class's codec, ``DecimalCodec``,
+as shown in the following example:
 
 .. code-block:: python
 
    class DecimalIntCodec(DecimalCodec):
        @property
        def python_type(self):
-           # The Python type acted upon by this type codec
+           # The Python type encoded by this type codec
            return DecimalInt
 
 You can then add the sublcass's type codec to the type registry and encode instances
@@ -252,7 +256,6 @@ of the custom type:
       codec_options = CodecOptions(type_registry=type_registry)
 
       collection = db.get_collection("test", codec_options=codec_options)
-      collection.drop()
       collection.insert_one({"num": DecimalInt("45.321")})
 
       my_doc = collection.find_one()
@@ -273,7 +276,7 @@ Define a Fallback Encoder
 
 You can also register a **fallback encoder**, a callable to encode types not recognized
 by BSON and for which no type codec has been registered.
-Like the ``transform_python()`` method, the fallback encoder accepts an unencodable
+The fallback encoder accepts an unencodable
 value as a parameter and returns a BSON-encodable value.
 
 The following fallback encoder encodes Python's ``Decimal`` type to a ``Decimal128``:
@@ -332,9 +335,10 @@ class:
 
 Encode Unknown Types
 ~~~~~~~~~~~~~~~~~~~~
+.. TODO: consider new example
 
 Because fallback encoders don't need to declare the types that they encode
-beforehand, you can them in cases where a ``TypeEncoder`` doesn't work.
+beforehand, you can use them in cases where a ``TypeEncoder`` doesn't work.
 For example, you can use a fallback encoder to save arbitrary objects to MongoDB.
 Consider the following arbitrary custom types: