Docstrings for modules all over sugar and shell.

These are just the doc strings I created as I was spelunking
through to see how Sugar manages launching applications.  The
resulting auto-documentation is neither polished or finished,
but it should help people reading the code somewhat.

There are a few minor code cleanups:

  * activityhandle (replacing C idiom for initialisation with
    a Python one)
  * bundle registry (using a parameterised directory name so
    that it shows up in the documentation)
  * validate_activity_id function, use isinstance( item, (str,unicode))
    for the query, rather than two separate checks with isinstance

sugar/activity/activity.py

@@ -1,3 +1,8 @@
+"""Base class for Python-coded activities
+
+This is currently the only reference for what an 
+activity must do to participate in the Sugar desktop.
+"""
 # Copyright (C) 2006, Red Hat, Inc.
 #
 # This library is free software; you can redistribute it and/or
@@ -29,6 +34,26 @@ class Activity(Window, gtk.Container):
     """Base Activity class that all other Activities derive from."""
     __gtype_name__ = 'SugarActivity'
     def __init__(self, handle):
+        """Initialise the Activity 
+        
+        handle -- sugar.activity.activityhandle.ActivityHandle
+            instance providing the activity id and access to the 
+            presence service which *may* provide sharing for this 
+            application
+        
+        Side effects: 
+        
+            Sets the gdk screen DPI setting (resolution) to the 
+            Sugar screen resolution.
+            
+            Connects our "destroy" message to our _destroy_cb
+            method.
+        
+            Creates a base gtk.Window within this window.
+            
+            Creates an ActivityService (self._bus) servicing
+            this application.
+        """
         Window.__init__(self)
 
         self.connect('destroy', self._destroy_cb)
@@ -105,6 +130,7 @@ class Activity(Window, gtk.Container):
         return False
 
     def _destroy_cb(self, window):
+        """Destroys our ActivityService and sharing service"""
         if self._bus:
             del self._bus
             self._bus = None
@@ -112,4 +138,6 @@ class Activity(Window, gtk.Container):
             self._pservice.unregister_service(self._service)
 
 def get_bundle_path():
+    """Return the bundle path for the current process' bundle
+    """
     return os.environ['SUGAR_BUNDLE_PATH']