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

1 files changed, 23 insertions, 1 deletions

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: