Update avatar documentation

Add missing function and fixes some typos and formatting.

1 files changed, 25 insertions, 11 deletions

diff --git a/docs/Avatars.md b/docs/Avatars.md
index a24c1f7c..31138af7 100644
--- a/docs/Avatars.md
+++ b/docs/Avatars.md
@@ -11,8 +11,8 @@ way for one user to identify another in the friend list.
 This document describes the implementation of avatars in the Tox protocol,
 according to the following design considerations:
 
-  - Avatars are handled as private information, i.e., they are only exchanged over
-    Tox encrypted channels among previously authenticated friends;
+  - Avatars are handled as private information, i.e., they are only exchanged
+    over Tox encrypted channels among previously authenticated friends;
 
   - The library treats all images as blobs and does not interpret or
     understand image formats. It only ensures that the avatar data sent by
@@ -85,14 +85,15 @@ Tox protocol:
     connects to the network, changes his avatar, or in reply to an **avatar
     information request**. They are delivered by a very lightweight message
     but with information enough to allow a user to validate or discard an
-    avatar from the local cache and to decide if it is interesting to request the
-    avatar data from the peer.
+    avatar from the local cache and to decide if it is interesting to request
+    the avatar data from the peer.
 
     This event contains two data fields: (1) the image format, and (2) the
-    cryptographic hash of the actual image data. The image format may be NONE
-    (for users who have no avatar or removed their avatars) or PNG. The
+    cryptographic hash of the current image data. The image format may be
+    NONE (for users who have no avatar or removed their avatars) or PNG. The
     cryptographic hash is intended to be compared with the hash of the
-    currently cached avatar (if any) in order to check if it is still up to date.
+    currently cached avatar (if any) in order to check if it is still up to
+    date.
 
   - **Avatar Information Requests** are very lightweight messages sent by a
     user asking for an **avatar information notification**. They may be sent
@@ -145,6 +146,9 @@ TOX_AVATAR_FORMAT;
 /* Set the user avatar image data. */
 int tox_set_avatar(Tox *tox, uint8_t format, const uint8_t *data, uint32_t length);
 
+/* Removes the user avatar image data. */
+int tox_unset_avatar(Tox *tox);
+
 /* Get avatar data from the current user. */
 int tox_get_self_avatar(const Tox *tox, uint8_t *format, uint8_t *buf, uint32_t *length, uint32_t maxlen, uint8_t *hash);
 
@@ -201,6 +205,11 @@ void tox_callback_avatar_data(Tox *tox, void (*function)(Tox *tox, int32_t, uint
       * A client may not understand a particular image format and ignore
         avatars using it, but request and handle other formats;
 
+      * A client on a slow mobile network may ask for avatar information to
+        ensure its cached avatars are still valid, but do not request avatar
+        data. The same client may start asking for avatar data once it
+        connects through a fast network.
+
   - Clients SHOULD implement a local cache of avatars and do not request
     avatar data from other peers unless necessary;
 
@@ -253,7 +262,7 @@ Given the Tox data directory described in STS Draft v0.1.0:
   - The client's own avatar is not special and is stored like any other. This
     is partially for simplicity, and partially in anticipation of profiles.
 
-  - The avatar should be stored as its recieved, before any modifications by
+  - The avatar should be stored as its received, before any modifications by
     the client for display purposes.
 
   - The hash, as calculated by toxcore and passed in to the data callback,
@@ -269,7 +278,7 @@ Example for Linux and other Unix systems, assuming an user called "gildor":
     Tox data directory: /home/gildor/.config/tox/
     Tox data file:      /home/gildor/.config/tox/data
     Avatar data dir:    /home/gildor/.config/tox/avatars/
-    Gildor's avatar:    /home/gildor/.config/tox/avatars/E5809EEF5F11AB29B9BDF543C05B58DDF454AB9CA176C235C7699FDC2757DC33.png
+    Gildor's avatar:    /home/gildor/.config/tox/avatars/446F4E6F744D6564646C65496E546865416666616972734F6657697A61726473.png
     Elrond's avatar:    /home/gildor/.config/tox/avatars/43656C65627269616E20646F6E277420546F782E426164206D656D6F72696573.png
     Elrond's hash:      /home/gildor/.config/tox/avatars/43656C65627269616E20646F6E277420546F782E426164206D656D6F72696573.hash
     Elladan's avatar:   /home/gildor/.config/tox/avatars/49486174655768656E48756D616E735468696E6B49416D4D7942726F74686572.png
@@ -313,7 +322,12 @@ notifications and unnecessary data transfers.
 
 #### Removing the avatar from the current user
 
-To remove an avatar, an application must set it to `TOX_AVATAR_FORMAT_NONE`.
+To remove the current avatar, an application must call
+
+    tox_unset_avatar(tox);
+
+the effect is the same as setting the avatar format to `TOX_AVATAR_FORMAT_NONE`
+and with no data:
 
     tox_set_avatar(tox, TOX_AVATAR_FORMAT_NONE, NULL, 0);
 
@@ -555,7 +569,7 @@ from a client "B":
     If valid, "A" updates the 'bytes_received' counter and concatenates the
     newly arrived data to the buffer.
 
-    The "A" checks if all the data was already received by comparing the
+    Then "A" checks if all the data was already received by comparing the
     counter 'bytes_received' with the field 'total_length'. If they are
     equal, "A" takes a SHA-256 hash of the data and compares it with the
     hash stored in the field 'hash' received from the first