RUBY-1977 Document and repair edge cases in ByteBuffer (#138)

* Revise ByteBuffer documentation

* Reorder the methods

* Document rewind in tutorial

* Include C extension in documentation

* C extension documentation

* docs

* Split byte buffer tests

* Add empty buffer length test

* Rewind test for write position

* Move rewind test to general byte buffer file

* put_bytes with null bytes test

* put_bytes documentation

* Move put_bytes tests next to put_byte

* Document put_byte and prohibit strings of length != 1

* Rename BSON_TYPE_OBJECT to BSON_TYPE_DOCUMENT

* Order types as they are listed in the bson spec

* Putting partial strings is private helper

* Bson string writing is also a private helper

* put_string documentation

* Move put_string tests

* Add put_string with empty string test

* Use pvt_put_byte

* Number writing documentation

* Do not duplicate docstrings

* put_cstring docstring

* Documentation for positions

* Document to_s

* put_decimal128

* Documentation and range checks in replace_int32

* More replace_int32 tests

* put_symbol and null bytes

* Fix signedness warning

* Fix the length comparison again

* put_hash and put_array docs

* JRuby compatibility

* JRuby implementation changes for replace_int32

* JRuby implementation changes for put_byte

* JRuby 9.1 compatibility

Author: p-mongo

.yardopts

@@ -1,2 +1,3 @@
 lib/**/*.rb
+ext/bson/*.c
 -o yard-docs

docs/tutorials/bson-v4.txt

@@ -68,22 +68,22 @@ you wish to instantiate and passing it a ``BSON::ByteBuffer`` instance.
   String.from_bson(byte_buffer)
   BSON::Int32.from_bson(byte_buffer)
 
+
 Byte Buffers
 ------------
 
-In 4.0, BSON introduced the use of native byte buffers in both MRI and JRuby
-instead of using ``StringIO``. This was done for performance improvements.
+BSON library 4.0 introduces the use of native byte buffers in MRI and JRuby
+instead of using ``StringIO``, for improved performance.
 
-API
-```
+Writing
+```````
 
-A ``BSON::ByteBuffer`` can be instantiated with nothing (for write mode) or
-with a string of raw bytes (for read mode).
+To create a ``ByteBuffer`` for writing (i.e. serializing to BSON),
+instantiate ``BSON::ByteBuffer`` with no arguments:
 
 .. code-block:: ruby
 
   buffer = BSON::ByteBuffer.new # a write mode buffer.
-  buffer = BSON::ByteBuffer.new(string) # a read mode buffer.
 
 Writing to the buffer is done via the following API:
 
@@ -99,6 +99,32 @@ Writing to the buffer is done via the following API:
   # writes the string to the buffer.
   buffer.put_cstring(value)
 
+To obtain the serialized data as a byte string (for example, to send the data
+over a socket), call ``to_s`` on the buffer:
+
+.. code-block:: ruby
+
+  buffer = BSON::ByteBuffer.new
+  buffer.put_string('testing')
+  socket.write(buffer.to_s)
+
+.. note::
+
+  ``ByteBuffer`` keeps track of read and write positions separately.
+  There is no way to rewind the buffer for writing - ``rewind`` only affects
+  the read position.
+
+
+Reading
+```````
+
+To create a ``ByteBuffer`` for reading (i.e. deserializing from BSON),
+instantiate ``BSON::ByteBuffer`` with a byte string as the argument:
+
+.. code-block:: ruby
+
+  buffer = BSON::ByteBuffer.new(string) # a read mode buffer.
+
 Reading from the buffer is done via the following API:
 
 .. code-block:: ruby
@@ -111,19 +137,22 @@ Reading from the buffer is done via the following API:
   buffer.get_int64 # Pulls a 64-bit integer (8 bytes) from the buffer.
   buffer.get_string # Pulls a UTF-8 string from the buffer.
 
-Converting a buffer to its raw bytes (for example, for sending over a socket)
-is done by simply calling ``to_s`` on the buffer.
+To restart reading from the beginning of a buffer, use ``rewind``:
 
 .. code-block:: ruby
 
-  buffer = BSON::ByteBuffer.new
-  buffer.put_string('testing')
-  socket.write(buffer.to_s)
+  buffer.rewind
+
+.. note::
+
+  ``ByteBuffer`` keeps track of read and write positions separately.
+  ``rewind`` only affects the read position.
+
 
-Supported Objects
+Supported Classes
 -----------------
 
-Core Ruby objects that have representations in the BSON specification and
+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``.

ext/bson/bson-native.h

@@ -31,13 +31,13 @@ rb_bson_utf8_validate (const char *utf8, /* IN */
 #define HOST_NAME_HASH_MAX 256
 #endif
 
-#define BSON_TYPE_DOUBLE 1
-#define BSON_TYPE_STRING 2
-#define BSON_TYPE_OBJECT 3
-#define BSON_TYPE_ARRAY 4
-#define BSON_TYPE_INT32 16
-#define BSON_TYPE_INT64 18
-#define BSON_TYPE_BOOLEAN 8
+#define BSON_TYPE_DOUBLE        1
+#define BSON_TYPE_STRING        2
+#define BSON_TYPE_DOCUMENT      3
+#define BSON_TYPE_ARRAY         4
+#define BSON_TYPE_BOOLEAN       8
+#define BSON_TYPE_INT32         16
+#define BSON_TYPE_INT64         18
 
 typedef struct {
   size_t size;
@@ -78,13 +78,11 @@ VALUE rb_bson_byte_buffer_get_hash(VALUE self);
 VALUE rb_bson_byte_buffer_get_array(VALUE self);
 VALUE rb_bson_byte_buffer_put_byte(VALUE self, VALUE byte);
 VALUE rb_bson_byte_buffer_put_bytes(VALUE self, VALUE bytes);
-VALUE rb_bson_byte_buffer_put_bson_partial_string(VALUE self, const char *str, int32_t length);
 VALUE rb_bson_byte_buffer_put_cstring(VALUE self, VALUE string);
 VALUE rb_bson_byte_buffer_put_decimal128(VALUE self, VALUE low, VALUE high);
 VALUE rb_bson_byte_buffer_put_double(VALUE self, VALUE f);
 VALUE rb_bson_byte_buffer_put_int32(VALUE self, VALUE i);
 VALUE rb_bson_byte_buffer_put_int64(VALUE self, VALUE i);
-VALUE rb_bson_byte_buffer_put_bson_string(VALUE self, const char *str, int32_t length);
 VALUE rb_bson_byte_buffer_put_string(VALUE self, VALUE string);
 VALUE rb_bson_byte_buffer_put_symbol(VALUE self, VALUE symbol);
 VALUE rb_bson_byte_buffer_put_hash(VALUE self, VALUE hash, VALUE validating_keys);

ext/bson/bytebuf.c

@@ -90,19 +90,15 @@ VALUE rb_bson_byte_buffer_length(VALUE self)
   return UINT2NUM(READ_SIZE(b));
 }
 
-/**
- * Get the read position.
- */
+/* The docstring is in init.c. */
 VALUE rb_bson_byte_buffer_read_position(VALUE self)
 {
   byte_buffer_t *b;
   TypedData_Get_Struct(self, byte_buffer_t, &rb_byte_buffer_data_type, b);
   return INT2NUM(b->read_position);
 }
 
-/**
- * Reset the read position to the beginning of the byte buffer.
- */
+/* The docstring is in init.c. */
 VALUE rb_bson_byte_buffer_rewind(VALUE self)
 {
   byte_buffer_t *b;
@@ -112,19 +108,15 @@ VALUE rb_bson_byte_buffer_rewind(VALUE self)
   return self;
 }
 
-/**
- * Get the write position.
- */
+/* The docstring is in init.c. */
 VALUE rb_bson_byte_buffer_write_position(VALUE self)
 {
   byte_buffer_t *b;
   TypedData_Get_Struct(self, byte_buffer_t, &rb_byte_buffer_data_type, b);
   return INT2NUM(b->write_position);
 }
 
-/**
- * Convert the buffer to a string.
- */
+/* The docstring is in init.c. */
 VALUE rb_bson_byte_buffer_to_s(VALUE self)
 {
   byte_buffer_t *b;