Fix long-standing issue with user updates not dispatching properly.

This fix is long coming. For a long time due to the addition of a
global user cache, the on_member_update event would only have the
updated user in the very first dispatch due to a quirk in the reference
only being updated once.

In order to fix this issue two things had to change:

1. There had to be a new event, `on_user_update` to complement
   the equivalent member event.
2. Unnecessary copies of User had to be removed to compensate for the
   performance hit from the diffing.

While doing these two fixes I also re-evaluated some more unnecessary
copies done during the PRESENCE_UPDATE to add member case while
fetch_offline_members=False is set or due to chunking issues. The
number of copies was brought down from 2 to 1, discounting the original
Member creation. Unsure on the benefits of this one, however.

N.B: this doesn't change the pre-existing behaviour of on_member_update

1 files changed, 13 insertions, 1 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 7371537d..5f1466e5 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -439,13 +439,25 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
     - status
     - game playing
-    - avatar
     - nickname
     - roles
 
     :param before: The :class:`Member` that updated their profile with the old info.
     :param after: The :class:`Member` that updated their profile with the updated info.
 
+.. function:: on_user_update(before, after)
+
+    Called when a :class:`User` updates their profile.
+
+    This is called when one or more of the following things change:
+
+    - avatar
+    - username
+    - discriminator
+
+    :param before: The :class:`User` that updated their profile with the old info.
+    :param after: The :class:`User` that updated their profile with the updated info.
+
 .. function:: on_guild_join(guild)
 
     Called when a :class:`Guild` is either created by the :class:`Client` or when the