Document the breaking change with the new dictionary storage change.

Since the only things dict views support are iteration we should
advise people who want the old behaviour to change it to a list.

3 files changed, 41 insertions, 4 deletions

diff --git a/discord/client.py b/discord/client.py
index 4c06dcbf..77b71466 100644
--- a/discord/client.py
+++ b/discord/client.py
@@ -88,9 +88,9 @@ class Client:
         Represents the current voice connection. None if you are not connected
         to a voice channel. To connect to voice use :meth:`join_voice_channel`.
         To query the voice connection state use :meth:`is_voice_connected`.
-    servers : list of :class:`Server`
+    servers : iterable of :class:`Server`
         The servers that the connected client is a member of.
-    private_channels : list of :class:`PrivateChannel`
+    private_channels : iterable of :class:`PrivateChannel`
         The private channels that the connected client is participating on.
     messages
         A deque_ of :class:`Message` that the client has received from all
diff --git a/discord/server.py b/discord/server.py
index 66ae3cd6..2d2afe6b 100644
--- a/discord/server.py
+++ b/discord/server.py
@@ -67,9 +67,9 @@ class Server(Hashable):
     afk_channel : :class:`Channel`
         The channel that denotes the AFK channel. None if it doesn't exist.
     members
-        A list of :class:`Member` that are currently on the server.
+        An iterable of :class:`Member` that are currently on the server.
     channels
-        A list of :class:`Channel` that are currently on the server.
+        An iterable of :class:`Channel` that are currently on the server.
     icon : str
         The server's icon.
     id : str
diff --git a/docs/migrating.rst b/docs/migrating.rst
index 2cfa2bc6..c47986a2 100644
--- a/docs/migrating.rst
+++ b/docs/migrating.rst
@@ -122,6 +122,43 @@ After:
 In order for you to ``yield from`` or ``await`` a coroutine then your function must be decorated
 with ``@asyncio.coroutine`` or ``async def``.
 
+.. _migrating-iterable:
+
+Iterables
+----------
+
+For performance reasons, many of the internal data structures were changed into a dictionary to support faster
+lookup. As a consequence, this meant that some lists that were exposed via the API have changed into iterables
+and not sequences. In short, this means that certain attributes now only support iteration and not any of the
+sequence functions.
+
+The affected attributes are as follows:
+
+- :attr:`Client.servers`
+- :attr:`Client.private_channels`
+- :attr:`Server.channels`
+- :attr:`Server.members`
+
+Some examples of previously valid behaviour that is now invalid
+
+.. code-block:: python
+
+    if client.servers[0].name == "test":
+        # do something
+
+Since they are no longer ``list``\s, they no longer support indexing or any operation other than iterating.
+In order to get the old behaviour you should explicitly cast it to a list.
+
+.. code-block:: python
+
+    servers = list(client.servers)
+    # work with servers
+
+.. warning::
+
+    Due to internal changes of the structure, the order you receive the data in
+    is not in a guaranteed order.
+
 .. _migrating-enums:
 
 Enumerators