DOCSP-44433: Compare BSON::Binary objects (#142)

Author: norareidy

source/data-formats/bson.txt

@@ -227,16 +227,16 @@ specific to the specification:
 ``BSON::Binary``
 ~~~~~~~~~~~~~~~~
 
-Use ``BSON::Binary`` objects to store arbitrary binary data. The ``Binary``
-objects can be constructed from binary strings as follows:
+Use ``BSON::Binary`` objects to store arbitrary binary data. You can construct
+``Binary`` objects from binary strings, as shown in the following code:
 
 .. code-block:: ruby
 
   BSON::Binary.new("binary_string")
   # => <BSON::Binary:0x47113101192900 type=generic data=0x62696e6172795f73...>
 
 By default, ``Binary`` objects are created with BSON binary subtype 0
-(``:generic``). The subtype can be explicitly specified to indicate that
+(``:generic``). You can explicitly specify the subtype to indicate that
 the bytes encode a particular type of data:
 
 .. code-block:: ruby
@@ -247,8 +247,8 @@ the bytes encode a particular type of data:
 Valid subtypes are ``:generic``, ``:function``, ``:old``, ``:uuid_old``,
 ``:uuid``, ``:md5`` and ``:user``.
 
-The data and the subtype can be retrieved from ``Binary`` instances using
-``data`` and ``type`` attributes, as follows:
+You can use the ``data`` and ``type`` attributes to retrieve a
+``Binary`` object's data and the subtype, as shown in the following code:
 
 .. code-block:: ruby
 
@@ -258,6 +258,10 @@ The data and the subtype can be retrieved from ``Binary`` instances using
   binary.type
   => :user
 
+You can compare ``Binary`` objects by using the ``<=>`` operator, which allows
+you to sort objects that have the same binary subtype. To compare ``Binary`` objects,
+ensure that you install v5.0.2 or later of the BSON library.
+
 .. note::
 
   ``BSON::Binary`` objects always store the data in ``BINARY`` encoding,