[docs] Revise BinData annotation and mapping documentation

Author: jmikola

docs/en/reference/annotations-reference.rst

@@ -41,10 +41,8 @@ For additional information on using ``@AlsoLoad``, see
 @Bin
 ----
 
-Alias of @Field, with "type" attribute set to
-"bin". Converts value to
-MongoBinData http://www.php.net/manual/en/class.mongobindata.php,
-using MongoBinData::BYTE\_ARRAY type.
+Alias of `@Field`_, with "type" attribute set to "bin". Converts value to
+`MongoBinData`_ with ``MongoBinData::GENERIC`` sub-type.
 
 .. code-block:: php
 
@@ -56,10 +54,8 @@ using MongoBinData::BYTE\_ARRAY type.
 @BinCustom
 ----------
 
-Alias of @Field, with "type" attribute set to
-"bin\_custom". Converts value to
-MongoBinData http://www.php.net/manual/en/class.mongobindata.php,
-using MongoBinData::CUSTOM type.
+Alias of `@Field`_, with "type" attribute set to "bin\_custom". Converts
+value to `MongoBinData`_ with ``MongoBinData::CUSTOM`` sub-type.
 
 .. code-block:: php
 
@@ -71,10 +67,8 @@ using MongoBinData::CUSTOM type.
 @BinFunc
 --------
 
-Alias of @Field, with "type" attribute set to
-"bin\_func". Converts value to
-MongoBinData http://www.php.net/manual/en/class.mongobindata.php,
-using MongoBinData::FUNC type.
+Alias of `@Field`_, with "type" attribute set to "bin\_func". Converts value to
+`MongoBinData`_ with ``MongoBinData::FUNC`` sub-type.
 
 .. code-block:: php
 
@@ -86,10 +80,8 @@ using MongoBinData::FUNC type.
 @BinMD5
 -------
 
-Alias of @Field, with "type" attribute set to
-"bin\_md5". Converts value to
-MongoBinData http://www.php.net/manual/en/class.mongobindata.php,
-using MongoBinData::MD5 type.
+Alias of `@Field`_, with "type" attribute set to "bin\_md5". Converts value to
+`MongoBinData`_ with ``MongoBinData::MD5`` sub-type.
 
 .. code-block:: php
 
@@ -101,10 +93,8 @@ using MongoBinData::MD5 type.
 @BinUUID
 --------
 
-Alias of @Field, with "type" attribute set to
-"bin\_uuid". Converts value to
-MongoBinData http://www.php.net/manual/en/class.mongobindata.php,
-using MongoBinData::UUID type.
+Alias of `@Field`_, with "type" attribute set to "bin\_uuid". Converts value to
+`MongoBinData`_ with ``MongoBinData::UUID`` sub-type.
 
 .. code-block:: php
 
@@ -1155,3 +1145,5 @@ is used for pessimistic and optimistic locking. This is only compatible with
 
     /** @Int @Version */
     private $version;
+
+.. _MongoBinData: http://php.net/manual/en/class.mongobindata.php

docs/en/reference/basic-mapping.rst

@@ -184,7 +184,7 @@ You can read more about the available MongoDB types on `php.net <http://us.php.n
 Generally, the name of each built-in mapping type hints as to how the value will be converted.
 This list explains some of the less obvious mapping types:
 
--  ``bin``: string to MongoBinData instance with a "byte array" type
+-  ``bin``: string to MongoBinData instance with a "generic" type (default)
 -  ``bin_bytearray``: string to MongoBinData instance with a "byte array" type
 -  ``bin_custom``: string to MongoBinData instance with a "custom" type
 -  ``bin_func``: string to MongoBinData instance with a "function" type

lib/Doctrine/ODM/MongoDB/Types/BinDataByteArrayType.php

@@ -20,7 +20,10 @@
 namespace Doctrine\ODM\MongoDB\Types;
 
 /**
- * The BinDataByteArray type.
+ * The BinData type for byte array data.
+ *
+ * Per the BSON specification, this sub-type is deprecated in favor of the
+ * generic sub-type (BinDataType class).
  *
  * @since       1.0
  * @author      Jonathan H. Wage <jonwage@gmail.com>

lib/Doctrine/ODM/MongoDB/Types/BinDataCustomType.php

@@ -20,7 +20,7 @@
 namespace Doctrine\ODM\MongoDB\Types;
 
 /**
- * The BinDataCustom type.
+ * The BinData type for custom binary data.
  *
  * @since       1.0
  * @author      Jonathan H. Wage <jonwage@gmail.com>

lib/Doctrine/ODM/MongoDB/Types/BinDataFuncType.php

@@ -20,7 +20,7 @@
 namespace Doctrine\ODM\MongoDB\Types;
 
 /**
- * The BinDataFunc type.
+ * The BinData type for function data.
  *
  * @since       1.0
  * @author      Jonathan H. Wage <jonwage@gmail.com>

lib/Doctrine/ODM/MongoDB/Types/BinDataMD5Type.php

@@ -20,7 +20,10 @@
 namespace Doctrine\ODM\MongoDB\Types;
 
 /**
- * The BinDataMD5 type.
+ * The BinData type for binary MD5 data.
+ *
+ * Note: This sub-type is intended to store binary MD5 data. Considering using
+ * the basic string field type for storing hexadecimal MD5 strings.
  *
  * @since       1.0
  * @author      Jonathan H. Wage <jonwage@gmail.com>

lib/Doctrine/ODM/MongoDB/Types/BinDataType.php

@@ -20,7 +20,7 @@
 namespace Doctrine\ODM\MongoDB\Types;
 
 /**
- * The BinData type.
+ * The BinData type for generic data.
  *
  * @since       1.0
  * @author      Jonathan H. Wage <jonwage@gmail.com>

lib/Doctrine/ODM/MongoDB/Types/BinDataUUIDType.php

@@ -20,7 +20,7 @@
 namespace Doctrine\ODM\MongoDB\Types;
 
 /**
- * The BinDataUUID type.
+ * The BinData type for binary UUID data.
  *
  * @since       1.0
  * @author      Jonathan H. Wage <jonwage@gmail.com>