Update the documentation and examples

- update most of the examples with slixmpp
- change the help channels pointed out in the doc
- add a page listing differences from slixmpp and how to use asyncio
  nicely with slixmpp
- fix some in-code rst documentation

1 files changed, 47 insertions, 0 deletions

diff --git a/docs/differences.rst b/docs/differences.rst
new file mode 100644
index 00000000..e6e26d2c
--- /dev/null
+++ b/docs/differences.rst
@@ -0,0 +1,47 @@
+.. _differences:
+
+Differences from SleekXMPP
+==========================
+
+**Python 3.4+ only**
+    slixmpp will only work on python 3.4 and above.
+
+**Stanza copies**
+    The same stanza object is given through all the handlers; a handler that
+    edits the stanza object should make its own copy.
+
+**Replies**
+    Because stanzas are not copied anymore,
+    :meth:`Stanza.reply() <.StanzaBase.reply>` calls
+    (for :class:`IQs <.Iq>`, :class:`Messages <.Message>`, etc)
+    now return a new object instead of editing the stanza object
+    in-place.
+
+**Block and threaded arguments**
+    All the functions that had a ``threaded=`` or ``block=`` argument
+    do not have it anymore. Also, :meth:`.Iq.send` **does not block
+    anymore**.
+
+**Coroutine facilities**
+    **See** :ref:`using_asyncio`
+
+    If an event handler is a coroutine, it will be called asynchronously
+    in the event loop instead of inside the event caller.
+
+    A CoroutineCallback class has been added to create coroutine stream
+    handlers, which will be also handled in the event loop.
+
+    The :class:`~.slixmpp.stanza.Iq` object’s :meth:`~.slixmpp.stanza.Iq.send`
+    method now takes a *coroutine* parameter which, if set to ``True``,
+    will return a coroutine which will (asyncio-)block until the reply
+    is received.
+
+    Many plugins (WIP) calls which retrieve information also accept this
+    ``coroutine`` parameter.
+
+**Architectural differences**
+    slixmpp does not have an event queue anymore, and instead processes
+    handlers directly after receiving the XML stanza.
+
+.. note::
+    If you find something that doesn’t work but should, please report it.