RUBY-2043 Document binary encoding on Binary objects in tutorial (#151)

Author: p-mongo

docs/tutorials/bson-v4.txt

@@ -232,15 +232,53 @@ specific to the specification:
 ``BSON::Binary``
 ````````````````
 
-This is a representation of binary data. The raw data and the subtype must be
-provided when constructing.
+Use ``BSON::Binary`` objects to store arbitrary binary data. The ``Binary``
+objects can be constructed from binary strings as follows:
 
 .. code-block:: ruby
 
-  BSON::Binary.new(binary_data, :md5)
+  BSON::Binary.new("binary_string")
+  # => <BSON::Binary:0x47113101192900 type=generic data=0x62696e6172795f73...>
 
-Valid subtypes are: ``:generic``, ``:function``, ``:old``, ``:uuid_old``,
-``:uuid``, ``:md5``, ``:user``.
+By default, ``Binary`` objects are created with BSON binary subtype 0
+(``:generic``). The subtype can be explicitly specified to indicate that
+the bytes encode a particular type of data:
+
+.. code-block:: ruby
+
+  BSON::Binary.new("binary_string", :user)
+  # => <BSON::Binary:0x47113101225420 type=user data=0x62696e6172795f73...>
+
+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:
+
+.. code-block:: ruby
+
+  binary = BSON::Binary.new("binary_string", :user)
+  binary.data
+  => "binary_string"
+  binary.type
+  => :user
+
+.. note::
+
+  ``BSON::Binary`` objects always store the data in ``BINARY`` encoding,
+  regardless of the encoding that the string passed to the constructor
+  was in:
+
+  .. code-block:: ruby
+    
+    str = "binary_string"
+    str.encoding
+    # => #<Encoding:US-ASCII>
+    binary = BSON::Binary.new(str)
+    binary.data
+    # => "binary_string"
+    binary.data.encoding
+    # => #<Encoding:ASCII-8BIT>
 
 UUID Methods
 ~~~~~~~~~~~~