Update tostring docs, plus more doc cleanup

9 files changed, 60 insertions, 27 deletions

diff --git a/docs/api/basexmpp.rst b/docs/api/basexmpp.rst
index 841df3db..fa96322e 100644
--- a/docs/api/basexmpp.rst
+++ b/docs/api/basexmpp.rst
@@ -1,5 +1,5 @@
 ========
-basexmpp
+BaseXMPP
 ========
 
 .. module:: sleekxmpp.basexmpp
diff --git a/docs/api/clientxmpp.rst b/docs/api/clientxmpp.rst
index 8f87664e..a6f32c43 100644
--- a/docs/api/clientxmpp.rst
+++ b/docs/api/clientxmpp.rst
@@ -1,17 +1,8 @@
 ==========
-clientxmpp
+ClientXMPP
 ==========
 
 .. module:: sleekxmpp.clientxmpp
 
 .. autoclass:: ClientXMPP
-    
-    .. automethod:: connect
-
-    .. automethod:: register_feature
-
-    .. automethod:: get_roster
-
-    .. automethod:: update_roster
-
-    .. automethod:: del_roster_item
+    :members:
diff --git a/docs/api/componentxmpp.rst b/docs/api/componentxmpp.rst
new file mode 100644
index 00000000..989120c2
--- /dev/null
+++ b/docs/api/componentxmpp.rst
@@ -0,0 +1,8 @@
+=============
+ComponentXMPP
+=============
+
+.. module:: sleekxmpp.componentxmpp
+
+.. autoclass:: ComponentXMPP
+    :members:
diff --git a/docs/api/xmlstream/stanzabase.rst b/docs/api/xmlstream/stanzabase.rst
index afed7655..f575299e 100644
--- a/docs/api/xmlstream/stanzabase.rst
+++ b/docs/api/xmlstream/stanzabase.rst
@@ -1,13 +1,13 @@
 .. _stanzabase:
 
-==========
-stanzabase
-==========
+==============
+Stanza Objects
+==============
 
 .. module:: sleekxmpp.xmlstream.stanzabase
 
-The :mod:`sleekmxpp.xmlstream.stanzabase` module provides a wrapper for the
-standard :mod:`xml.etree.cElementTree` module that makes working with XML
+The :mod:`~sleekmxpp.xmlstream.stanzabase` module provides a wrapper for the
+standard :mod:`~xml.etree.ElementTree` module that makes working with XML
 less painful. Instead of having to manually move up and down an element
 tree and insert subelements and attributes, you can interact with an object
 that behaves like a normal dictionary or JSON object, which silently maps
@@ -52,7 +52,7 @@ elements of the original XML chunk.
 .. seealso::
     :ref:`create-stanza-interfaces`.
 
-Because the :mod:`sleekxmpp.xmlstream.stanzabase` module was developed
+Because the :mod:`~sleekxmpp.xmlstream.stanzabase` module was developed
 as part of an `XMPP <http://xmpp.org>`_ library, these chunks of XML are
 referred to as :term:`stanzas <stanza>`, and in SleekXMPP we refer to a
 subclass of :class:`ElementBase` which defines the interfaces needed for
diff --git a/docs/api/xmlstream/tostring.rst b/docs/api/xmlstream/tostring.rst
index 038b7876..82a8c2a5 100644
--- a/docs/api/xmlstream/tostring.rst
+++ b/docs/api/xmlstream/tostring.rst
@@ -1,17 +1,46 @@
-========
-tostring
-========
-
 .. module:: sleekxmpp.xmlstream.tostring
 
 .. _tostring:
 
 XML Serialization
------------------
+=================
+
+Since the XML layer of SleekXMPP is based on :mod:`~xml.etree.ElementTree`,
+why not just use the built-in :func:`~xml.etree.ElementTree.tostring`
+method? The answer is that using that method produces ugly results when
+using namespaces. The :func:`tostring()` method used here intelligently
+hides namespaces when able and does not introduce excessive namespace
+prefixes::
+
+    >>> from sleekxmpp.xmlstream.tostring import tostring
+    >>> from xml.etree import cElementTree as ET
+    >>> xml = ET.fromstring('<foo xmlns="bar"><baz /></foo>')
+    >>> ET.tostring(xml)
+    '<ns0:foo xmlns:ns0="bar"><ns0:baz /></foo>'
+    >>> tostring(xml)
+    '<foo xmlns="bar"><baz /></foo>'
+
+As a side effect of this namespace hiding, using :func:`tostring()` may
+produce unexpected results depending on how the :func:`tostring()` method
+is invoked. For example, when sending XML on the wire, the main XMPP
+stanzas with their namespace of ``jabber:client`` will not include the
+namespace because that is already declared by the stream header. But, if
+you create a :class:`~sleekxmpp.stanza.message.Message` instance and dump
+it to the terminal, the ``jabber:client`` namespace will appear.
 
 .. autofunction:: tostring
 
 Escaping Special Characters
 ---------------------------
 
+In order to prevent errors when sending arbitrary text as the textual
+content of an XML element, certain characters must be escaped. These
+are: ``&``, ``<``, ``>``, ``"``, and ``'``. The default escaping
+mechanism is to replace those characters with their equivalent escape
+entities: ``&amp;``, ``&lt;``, ``&gt;``, ``&apos;``, and ``&quot;``.
+
+In the future, the use of CDATA sections may be allowed to reduce the
+size of escaped text or for when other XMPP processing agents do not
+undertand these entities.
+
 .. autofunction:: xml_escape
diff --git a/docs/conf.py b/docs/conf.py
index 8a49e062..cbebd6ce 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -218,3 +218,5 @@ man_pages = [
     ('index', 'sleekxmpp', u'SleekXMPP Documentation',
      [u'Nathan Fritz, Lance Stout'], 1)
 ]
+
+intersphinx_mapping = {'python': ('http://docs.python.org/3.2', 'python-objects.inv')}
diff --git a/docs/index.rst b/docs/index.rst
index 525a479f..cb5b327e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -110,8 +110,10 @@ API Reference
     
     event_index
     api/clientxmpp
+    api/componentxmpp
     api/basexmpp
-    api/xmlstream/index
+    api/xmlstream/stanzabase
+    api/xmlstream/tostring
 
 Additional Info
 ---------------
diff --git a/docs/python-objects.inv b/docs/python-objects.inv
new file mode 100644
index 00000000..b7afc07e
--- /dev/null
+++ b/docs/python-objects.inv
diff --git a/sleekxmpp/xmlstream/tostring.py b/sleekxmpp/xmlstream/tostring.py
index ed58049e..8e729f79 100644
--- a/sleekxmpp/xmlstream/tostring.py
+++ b/sleekxmpp/xmlstream/tostring.py
@@ -27,9 +27,7 @@ def tostring(xml=None, xmlns='', stanza_ns='', stream=None,
     elements that use those namespaces will not include the xmlns attribute
     in the output.
 
-    :param XML xml: The XML object to serialize. If the value is ``None``,
-                    then the XML object contained in this stanza
-                    object will be used.
+    :param XML xml: The XML object to serialize.
     :param string xmlns: Optional namespace of an element wrapping the XML
                          object.
     :param string stanza_ns: The namespace of the stanza object that contains
@@ -40,6 +38,8 @@ def tostring(xml=None, xmlns='', stanza_ns='', stream=None,
     :param bool top_level: Indicates that the element is the outermost
                            element.
 
+
+    :type xml: :py:class:`~xml.etree.ElementTree.Element`
     :type stream: :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
 
     :rtype: Unicode string
@@ -114,6 +114,7 @@ def xml_escape(text):
     """Convert special characters in XML to escape sequences.
 
     :param string text: The XML text to convert.
+    :rtype: Unicode string
     """
     if sys.version_info < (3, 0):
         if type(text) != types.UnicodeType: