Overall roles and operation of the activity classes.

Note on return value for factory service.

sugar/activity/__init__.py

@@ -0,0 +1,47 @@
+"""Activity implementation code for Sugar-based activities
+
+Each activity within the OLPC environment must provide two
+dbus services.  The first, patterned after the 
+
+    sugar.activity.activityfactory.ActivityFactory
+
+class is responsible for providing a "create" method which 
+takes a small dictionary with values corresponding to a 
+
+    sugar.activity.activityhandle.ActivityHandle
+
+describing an individual instance of the activity.  The 
+ActivityFactory service is registered with dbus using the 
+global
+
+    sugar.activity.bundleregistry.BundleRegistry 
+
+service, which creates dbus .service files in a well known
+directory.  Those files tell dbus what executable to run 
+in order to load the ActivityFactory which will provide 
+the creation service.
+
+Each activity so registered is described by a
+
+    sugar.activity.bundle.Bundle
+
+instance, which parses a specially formatted activity.info 
+file (stored in the activity directory's ./activity 
+subdirectory).  The 
+
+    sugar.activity.bundlebuilder
+
+module provides facilities for the standard setup.py module 
+which produces and registers bundles from activity source 
+directories.
+
+Once instantiated by the ActivityFactory's create method,
+each activity must provide an introspection API patterned 
+after the
+
+    sugar.activity.activityservice.ActivityService
+
+class.  This class allows for querying the ID of the root 
+window, requesting sharing across the network, and basic
+"what type of application are you" queries.
+"""

sugar/activity/activityfactoryservice.py

@@ -99,6 +99,8 @@ class ActivityFactoryService(dbus.service.Object):
         handle -- sugar.activity.activityhandle.ActivityHandle
             compatible dictionary providing the instance-specific
             values for the new instance 
+        
+        returns xid for the created instance' root window
         """
         activity_handle = activityhandle.create_from_dict(handle)
         activity = self._constructor(activity_handle)