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

2 files changed, 82 insertions, 1 deletions

diff --git a/shell/model/homeactivity.py b/shell/model/homeactivity.py
index 9570c1b..cb71d8e 100644
--- a/shell/model/homeactivity.py
+++ b/shell/model/homeactivity.py
@@ -25,6 +25,13 @@ from sugar.presence import presenceservice
 from sugar import profile
 
 class HomeActivity(gobject.GObject):
+    """Activity which appears in the "Home View" of the Sugar shell
+    
+    This class stores the Sugar Shell's metadata regarding a
+    given activity/application in the system.  It interacts with
+    the sugar.activity.* modules extensively in order to 
+    accomplish its tasks.
+    """
     __gsignals__ = {
         'launch-timeout':          (gobject.SIGNAL_RUN_FIRST,
                                     gobject.TYPE_NONE, 
@@ -32,6 +39,15 @@ class HomeActivity(gobject.GObject):
     }
 
     def __init__(self, bundle, activity_id):
+        """Initialise the HomeActivity
+        
+        bundle -- sugar.activity.bundle.Bundle instance,
+            provides the information required to actually
+            create the new instance.  This is, in effect,
+            the "type" of activity being created.
+        activity_id -- unique identifier for this instance
+            of the activity type
+        """
         gobject.GObject.__init__(self)
         self._window = None
         self._xid = None
@@ -52,6 +68,8 @@ class HomeActivity(gobject.GObject):
         self._launch_timeout_id = 0
 
     def _launch_timeout_cb(self, user_data=None):
+        """Callback for launch operation timeouts
+        """
         logging.debug("Activity %s (%s) launch timed out" %
                       (self._activity_id, self.get_type))
         self._launch_timeout_id = 0
@@ -78,17 +96,33 @@ class HomeActivity(gobject.GObject):
         self._service = service
 
     def get_service(self):
+        """Retrieve the application's sugar introspection service
+        
+        Note that non-native Sugar applications will not have
+        such a service, so the return value will be None in
+        those cases.
+        """
         return self._service
 
     def get_title(self):
+        """Retrieve the application's root window's suggested title"""
         if not self._launched:
             raise RuntimeError("Activity is still launching.")
         return self._window.get_name()
 
     def get_icon_name(self):
+        """Retrieve the bundle's icon (file) name"""
         return self._bundle.get_icon()
     
     def get_icon_color(self):
+        """Retrieve the appropriate icon colour for this activity
+        
+        Uses activity_id to index into the PresenceService's 
+        set of activity colours, if the PresenceService does not
+        have an entry (implying that this is not a Sugar-shared application)
+        uses the local user's profile.get_color() to determine the
+        colour for the icon.
+        """
         pservice = presenceservice.get_instance()
         activity = pservice.get_activity(self._activity_id)
         if activity != None:
@@ -97,28 +131,53 @@ class HomeActivity(gobject.GObject):
             return profile.get_color()
         
     def get_activity_id(self):
+        """Retrieve the "activity_id" passed in to our constructor
+        
+        This is a "globally likely unique" identifier generated by
+        sugar.util.unique_id
+        """
         return self._activity_id
 
     def get_xid(self):
+        """Retrieve the X-windows ID of our root window"""
         if not self._launched:
             raise RuntimeError("Activity is still launching.")
         return self._xid
 
     def get_window(self):
+        """Retrieve the X-windows root window of this application
+        
+        This was stored by the set_window method, which was 
+        called by HomeModel._add_activity, which was called 
+        via a callback that looks for all 'window-opened'
+        events.
+        
+        HomeModel currently uses a dbus service query on the
+        activity to determine to which HomeActivity the newly
+        launched window belongs.
+        """
         if not self._launched:
             raise RuntimeError("Activity is still launching.")
         return self._window
 
     def get_type(self):
+        """Retrieve bundle's "service_name" for future reference"""
         return self._bundle.get_service_name()
 
     def get_shared(self):
+        """Return whether this activity is using Presence service sharing"""
         if not self._launched:
             raise RuntimeError("Activity is still launching.")
         return self._service.get_shared()
 
     def get_launch_time(self):
+        """Return the time at which the activity was first launched
+        
+        Format is floating-point time.time() value 
+        (seconds since the epoch)
+        """
         return self._launch_time
 
     def get_launched(self):
+        """Return whether we have bound our top-level window yet"""
         return self._launched
diff --git a/shell/model/homemodel.py b/shell/model/homemodel.py
index 9aa47e2..0b1eeb5 100644
--- a/shell/model/homemodel.py
+++ b/shell/model/homemodel.py
@@ -28,7 +28,19 @@ _SERVICE_NAME = "org.laptop.Activity"
 _SERVICE_PATH = "/org/laptop/Activity"
 
 class HomeModel(gobject.GObject):
-
+    """Model of the "Home" view (activity management)
+    
+    The HomeModel is basically the point of registration
+    for all running activities within Sugar.  It traps
+    events that tell the system there is a new activity
+    being created (generated by the activity factories),
+    or removed, as well as those which tell us that the
+    currently focussed activity has changed.
+    
+    The HomeModel tracks a set of HomeActivity instances,
+    which are tracking the window to activity mappings
+    the activity factories have set up.
+    """
     __gsignals__ = {
         'activity-launched':       (gobject.SIGNAL_RUN_FIRST,
                                     gobject.TYPE_NONE, 
@@ -124,6 +136,16 @@ class HomeModel(gobject.GObject):
         self.emit('activity-added', home_window)
 
     def _add_activity(self, window):
+        """Add the window to the set of windows we track
+        
+        At the moment this requires that something somewhere
+        have registered a dbus service with the XID of the 
+        new window that is used to bind the requested activity 
+        to the window.
+        
+        window -- gtk.Window instance representing a new 
+            normal, top-level window
+        """
         bus = dbus.SessionBus()
         xid = window.get_xid()
         try: