Update api docs for JID

docs/api/jid.rst

@@ -0,0 +1,7 @@
+Jabber IDs (JID)
+=================
+
+.. module:: sleekxmpp.xmlstream.jid
+
+.. autoclass:: JID
+    :members:

docs/conf.py

@@ -16,7 +16,7 @@ import sys, os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration -----------------------------------------------------
 

docs/index.rst

@@ -112,6 +112,7 @@ API Reference
     api/clientxmpp
     api/componentxmpp
     api/basexmpp
+    api/jid
     api/xmlstream/stanzabase
     api/xmlstream/tostring
     api/xmlstream/filesocket

sleekxmpp/xmlstream/jid.py

@@ -1,15 +1,22 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
+    sleekxmpp.xmlstream.jid
-    Copyright (C) 2010  Nathanael C. Fritz
+    ~~~~~~~~~~~~~~~~~~~~~~~
-    This file is part of SleekXMPP.
 
-    See the file LICENSE for copying permission.
+    This module allows for working with Jabber IDs (JIDs) by
+    providing accessors for the various components of a JID.
+
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from __future__ import unicode_literals
 
 
 class JID(object):
+
     """
     A representation of a Jabber ID, or JID.
 
@@ -19,18 +26,16 @@ class JID(object):
     When a resource is not used, the JID is called a bare JID.
     The JID is a full JID otherwise.
 
-    Attributes:
+    **JID Properties:**
-        jid      -- Alias for 'full'.
+        :jid: Alias for ``full``.
-        full     -- The value of the full JID.
+        :full: The value of the full JID.
-        bare     -- The value of the bare JID.
+        :bare: The value of the bare JID.
-        user     -- The username portion of the JID.
+        :user: The username portion of the JID.
-        domain   -- The domain name portion of the JID.
+        :domain: The domain name portion of the JID.
-        server   -- Alias for 'domain'.
+        :server: Alias for ``domain``.
-        resource -- The resource portion of the JID.
+        :resource: The resource portion of the JID.
 
-    Methods:
+    :param string jid: A string of the form ``'[user@]domain[/resource]'``.
-        reset      -- Use a new JID value.
-        regenerate -- Recreate the JID from its components.
     """
 
     def __init__(self, jid):
@@ -38,11 +43,9 @@ class JID(object):
         self.reset(jid)
 
     def reset(self, jid):
-        """
+        """Start fresh from a new JID string.
-        Start fresh from a new JID string.
 
-        Arguments:
+        :param string jid: A string of the form ``'[user@]domain[/resource]'``.
-            jid - The new JID value.
         """
         if isinstance(jid, JID):
             jid = jid.full
@@ -53,12 +56,10 @@ class JID(object):
         self._bare = None
 
     def __getattr__(self, name):
-        """
+        """Handle getting the JID values, using cache if available.
-        Handle getting the JID values, using cache if available.
 
-        Arguments:
+        :param name: One of: user, server, domain, resource,
-            name -- One of: user, server, domain, resource,
+                     full, or bare.
-                    full, or bare.
         """
         if name == 'resource':
             if self._resource is None and '/' in self._jid:
@@ -83,8 +84,7 @@ class JID(object):
             return self._bare or ""
 
     def __setattr__(self, name, value):
-        """
+        """Edit a JID by updating it's individual values, resetting the
-        Edit a JID by updating it's individual values, resetting the
         generated JID in the end.
 
         Arguments:
@@ -137,7 +137,5 @@ class JID(object):
         return self.full == other.full
 
     def __ne__(self, other):
-        """
+        """Two JIDs are considered unequal if they are not equal."""
-        Two JIDs are considered unequal if they are not equal.
-        """
         return not self == other