RUBY-2861 Document BigDecimal/Decimal128 differences (#269)

* RUBY-2681 add BigDecimal to supported classes

* RUBY-2861 add documentation for Decimal128 vs BigDecimal

* RUBY-2681 update language and fix sphinx errors

Author: neilshweky

docs/tutorials/bson-v4.txt

@@ -222,8 +222,8 @@ Supported Classes
 
 Core Ruby classes that have representations in the BSON specification and
 will have a ``to_bson`` method defined for them are: ``Object``, ``Array``,
-``FalseClass``, ``Float``, ``Hash``, ``Integer``, ``NilClass``, ``Regexp``,
-``String``, ``Symbol`` (deprecated), ``Time``, ``TrueClass``.
+``FalseClass``, ``Float``, ``Hash``, ``Integer``, ``BigDecimal``, ``NilClass``,
+``Regexp``, ``String``, ``Symbol`` (deprecated), ``Time``, ``TrueClass``.
 
 In addition to the core Ruby objects, BSON also provides some special types
 specific to the specification:
@@ -523,6 +523,26 @@ decimal rounding with exact precision.
   d = BigDecimal(1.28, 3)
   BSON::Decimal128.new(d)
 
+BSON::Decimal128 vs BigDecimal
+``````````````````````````````
+The ``BigDecimal`` ``from_bson`` and ``to_bson`` methods use the same
+``BSON::Decimal128`` methods under the hood. This leads to some limitations
+that are imposed on the ``BigDecimal`` values that can be serialized to BSON
+and those that can be deserialized from existing ``BSON::Decimal128`` BSON
+objects. This change was made because serializing ``BigDecimal`` instances as
+``BSON::Decimal128`` instances allows for more flexibility in terms of querying
+and aggregation in MongoDB. The limitations imposed on ``BigDecimal`` are as
+follows:
+
+- ``BSON::Decimal128`` has a limited range and precision, while ``BigDecimal``
+  has no restrictions in terms of range and precision. ``BSON::Decimal128`` has
+  a max value of approximately ``10^6145`` and a min value of approximately
+  ``-10^6145``, and has a maximum of 34 bits of precision.
+
+- ``BSON::Decimal128`` is able to accept signed ``NaN`` values, while
+  ``BigDecimal`` is not. All signed ``NaN`` values that are deserialized into
+  ``BigDecimal`` instances will be unsigned.
+
 ``Symbol``
 ----------