Add spec for ObjectMessage encoding and decoding

Author: VeskeR

textile/features.textile

@@ -1518,6 +1518,8 @@ h4. ObjectMessage
 ** @(OM3d)@ The size of the @extras@ property is the string length of its JSON representation
 ** @(OM3f)@ The size of the @clientId@ property is its string length
 ** @(OM3e)@ The size of a @null@ or omitted property is zero
+* @(OM4)@ For @ObjectMessage@ encoding see @ObjectData@ "OD4":#OD4 and @ObjectOperation@ "OOP5":#OOP5 encoding
+* @(OM5)@ For @ObjectMessage@ decoding see @ObjectData@ "OD5":#OD5 decoding
 
 h4. ObjectOperation
 
@@ -1530,16 +1532,23 @@ h4. ObjectOperation
 ** @(OOP3d)@ @counterOp@ @CounterOp@ object - the payload for the operation if it is an operation on a @Counter@ object type
 ** @(OOP3e)@ @map@ @Map@ object - the payload for the operation if the operation is @MAP_CREATE@. Defines the initial value for the @Map@ object
 ** @(OOP3f)@ @counter@ @Counter@ object - the payload for the operation if the operation is @COUNTER_CREATE@. Defines the initial value for the @Counter@ object
-** @(OOP3g)@ @nonce@ string - the nonce, must be present on @COUNTER_CREATE@ and @MAP_CREATE@ operations sent to the server
-** @(OOP3h)@ @initialValue@ binary - the initial value bytes for the object
-** @(OOP3i)@ @initialValueEncoding@ string - defines how the @initialValue@ should be interpreted. Should be @msgpack@ or @json@
+** @(OOP3g)@ @nonce@ string - the nonce. Must be present on @COUNTER_CREATE@ and @MAP_CREATE@ operations sent to the server. Should not be accessed by the client library if received from the server
+** @(OOP3h)@ @initialValue@ binary - the initial value bytes for the object. Must be present on @COUNTER_CREATE@ and @MAP_CREATE@ operations sent to the server. Should not be accessed by the client library if received from the server
+** @(OOP3i)@ @initialValueEncoding@ string - defines how the @initialValue@ should be interpreted by the server. Must be @msgpack@ or @json@. Must be present on @COUNTER_CREATE@ and @MAP_CREATE@ operations sent to the server. Should not be accessed by the client library if received from the server
 * @(OOP4)@ The size of the @ObjectOperation@ is calculated as follows:
 ** @(OOP4a)@ The size is the sum of the sizes of the @mapOp@, @counterOp@, @map@, and @counter@ properties
 ** @(OOP4b)@ The size of the @mapOp@ property is calculated per "MOP3":#MOP3
 ** @(OOP4c)@ The size of the @counterOp@ property is calculated per "COP3":#COP3
 ** @(OOP4d)@ The size of the @map@ property is calculated per "MAP4":#MAP4
 ** @(OOP4e)@ The size of the @counter@ property is calculated per "CNT3":#CNT3
 ** @(OOP4f)@ The size of a @null@ or omitted property is zero
+* @(OOP5)@ @ObjectOperation@ encoding:
+** @(OOP5a)@ When the MessagePack protocol is used:
+*** @(OOP5a1)@ A binary @ObjectOperation.initialValue@ is encoded as a MessagePack binary type
+*** @(OOP5a2)@ Set @ObjectOperation.initialValueEncoding@ to @msgpack@
+** @(OOP5b)@ When the JSON protocol is used:
+*** @(OOP5b1)@ A binary @ObjectOperation.initialValue@ is Base64-encoded and represented as a JSON string
+*** @(OOP5b2)@ Set @ObjectOperation.initialValueEncoding@ to @json@
 
 h4. ObjectState
 
@@ -1630,6 +1639,28 @@ h4. ObjectData
 ** @(OD3d)@ If set, the size of a @number@ property is 8
 ** @(OD3e)@ If set, the size of a @string@ property is its length
 ** @(OD3f)@ The size of a @null@ or omitted property is zero
+* @(OD4)@ @ObjectData@ encoding:
+** @(OD4a)@ Payloads must be booleans, binary, numbers, strings, or objects capable of JSON representation. Any other data type must not be permitted and result in an error with code 40013.
+** @(OD4b)@ When the MessagePack protocol is used:
+*** @(OD4b1)@ A boolean payload is encoded as a MessagePack boolean type, and the result is set on the @ObjectData.boolean@ attribute.
+*** @(OD4b2)@ A binary payload is encoded as a MessagePack binary type, and the result is set on the @ObjectData.bytes@ attribute.
+*** @(OD4b3)@ A number payload is encoded as a MessagePack number type, and the result is set on the @ObjectData.number@ attribute.
+*** @(OD4b4)@ A string payload is encoded as a MessagePack string type, and the result is set on the @ObjectData.string@ attribute.
+*** @(OD4b5)@ A payload consisting of an object capable of JSON representation is stringified as either a JSON object or array, encoded as a MessagePack string type, and the result is set on the @ObjectData.string@ attribute. The @ObjectData.encoding@ attribute is then set to "json".
+** @(OD4c)@ When the JSON protocol is used:
+*** @(OD4c1)@ A boolean payload is represented as a JSON boolean and set on the @ObjectData.boolean@ attribute.
+*** @(OD4c2)@ A binary payload is Base64-encoded and represented as a JSON string; the result is set on the @ObjectData.bytes@ attribute.
+*** @(OD4c3)@ A number payload is represented as a JSON number and set on the @ObjectData.number@ attribute.
+*** @(OD4c4)@ A string payload is represented as a JSON string and set on the @ObjectData.string@ attribute.
+*** @(OD4c5)@ A payload consisting of an object capable of JSON representation is stringified as either a JSON object or array, represented as a JSON string and the result is set on the @ObjectData.string@ attribute. The @ObjectData.encoding@ attribute is then set to "json".
+* @(OD5)@ @ObjectData@ decoding:
+** @(OD5a)@ When the MessagePack protocol is used:
+*** @(OD5a1)@ The payloads in @ObjectData.boolean@, @ObjectData.bytes@, @ObjectData.number@, and @ObjectData.string@ are decoded as their corresponding MessagePack types.
+*** @(OD5a2)@ If @ObjectData.encoding@ is set to "json", the @ObjectData.string@ content is decoded by parsing the string as JSON.
+** @(OD5b)@ When the JSON protocol is used:
+*** @(OD5b1)@ The payloads in @ObjectData.boolean@, @ObjectData.number@, and @ObjectData.string@ are decoded as their corresponding JSON types.
+*** @(OD5b2)@ The @ObjectData.bytes@ payload is Base64-decoded into a binary value.
+*** @(OD5b3)@ If @ObjectData.encoding@ is set to "json", the @ObjectData.string@ content is decoded by parsing the string as JSON.
 
 h4. Annotation