Merge pull request #530 from aeternity/fix_aens_update_documentation

Clarify and correct docs on AENSUpdateTx

Author: ThomasArts

AENS.md

@@ -291,8 +291,7 @@ pre-claimed|auction ---> claimed
 
 The pointers field in the name entry:
 * On `claim` transaction, is initialized to the empty dictionary.
-* On `update` transaction, is replaced with the pointers in the transaction,
-  keeping the order in the transaction.
+* On `update` transaction, is replaced with the pointers in the transaction.
 
 Note that `expire` is not an explicit message that is part
 of the protocol.
@@ -523,6 +522,12 @@ From Iris protocol upgrade, the following limitations on pointers apply:
 From Ceres hardfork, a new pointer target type is introduced:
   - A key can point to up to 1024 bytes of uninterpreted data (a bytearray)
 
+Note: An update containing the new pointer target type MUST use version 2 of
+the
+[serialization](serializations.md#name-service-update-transaction-version-2);
+and, an update _not_ containing the new target type MUST use version 1 of the
+[serialization](serializations.md#name-service-update-transaction-version-1).
+
 #### Transfer
 
 ```

serializations.md

@@ -533,7 +533,11 @@ Note: From Ceres protocol version `contract` can be a name (where the
 ]
 ```
 
-#### Name service update transaction (version 1, until Ceres release)
+#### Name service update transaction - version 1
+
+This is the serialization of an AENS Update transaction that does not contain
+raw data pointers.
+
 ```
 [ <account>    :: id()
 , <nonce>      :: int()
@@ -546,7 +550,11 @@ Note: From Ceres protocol version `contract` can be a name (where the
 ]
 ```
 
-#### Name service update transaction (version 2, from Ceres release)
+#### Name service update transaction - version 2
+
+Introduced in Ceres protocol; this is the serialization of an AENS Update
+transaction that contains one or more raw data pointers.
+
 ```
 [ <account>    :: id()
 , <nonce>      :: int()