Add and improve docs for sugar3.graphics.objectchooser

src/sugar3/graphics/objectchooser.py

@@ -42,16 +42,19 @@ FILTER_TYPE_ACTIVITY = 'activity'
 
 
 def get_preview_pixbuf(preview_data, width=-1, height=-1):
-    """Retrive a pixbuf with the content of the preview field
+    """
+    Retrive a pixbuf with the content of the preview field
 
-    Keyword arguments:
-    metadata -- the metadata dictionary.
-                Can't be None, use metadata.get('preview', '')
-    width -- the pixbuf width, if is not set, the default width will be used
-    height -- the pixbuf width, if is not set, the default height will be used
+    Args:
+        metadata (dictionary): the metadata dictionary. Can't be None, use metadata.get('preview', '')
 
-    Return: a Pixbuf or None if couldn't create it
+    Keyword Args:
+        width (int): the pixbuf width, if is not set, the default width will be used
+        height (int): the pixbuf width, if is not set, the default height will be used
 
+    Returns:
+        Pixbuf, the generated Pixbuf
+        None, if it could not be created
     """
     if width == -1:
         width = PREVIEW_SIZE[0]
@@ -99,22 +102,20 @@ def get_preview_pixbuf(preview_data, width=-1, height=-1):
 
 
 class ObjectChooser(object):
+    """
+    UI interface for objec choosers.
 
-    def __init__(self, parent=None, what_filter=None, filter_type=None,
-                 show_preview=False):
-        """Initialise the ObjectChoser
-
-        parent -- the widget calling ObjectChooser
+    Object choosers can be used by acivities to allow the user to select objects
+    from the file system or from some other similar source.
 
-        what_filter -- string
+    Keyword Args:
+        parent (:class:`Gtk.Widget`): the widget calling ObjectChooser
 
-            string should be an activity bundle_id or a generic mime
-            type as defined in mime.py used to determine which objects
+        what_filter (str): an activity bundle_id or a generic mime type as
+            defined in mime.py used to determine which objects
             will be presented in the object chooser
-
-        filter_type -- string
-
-            string should be one of [None, FILTER_TYPE_GENERIC_MIME,
+        
+        filter_type (str): should be one of [None, FILTER_TYPE_GENERIC_MIME,
             FILTER_TYPE_ACTIVITY, FILTER_TYPE_MIME_BY_ACTIVITY]
 
             If filter_type is None, the default behavior of the
@@ -136,13 +137,13 @@ class ObjectChooser(object):
             field and the mime types defined by the activity in the
             activity.info file.
 
-        show_preview -- boolean
-
-            if True will show the preview image asociated with
-            the object in the Journal. This option is only available
-            if filter_type is selected.
-        """
+        show_preview (bool): if True will show the preview image asociated with
+            the object in the Journal. This option is only available if
+            filter_type is selected.
+    """
 
+    def __init__(self, parent=None, what_filter=None, filter_type=None,
+                 show_preview=False):
         if parent is None:
             parent_xid = 0
         elif hasattr(parent, 'get_window') and hasattr(parent.get_window(),
@@ -170,6 +171,13 @@ class ObjectChooser(object):
         self._filter_type = filter_type
 
     def run(self):
+        """
+        Runs the object chooser and displays it.
+        
+        Returns:
+            Gtk.ResponseType constant, the response received from displaying the
+                object chooser.
+        """
         self._object_id = None
 
         self._main_loop = GObject.MainLoop()
@@ -211,12 +219,21 @@ class ObjectChooser(object):
         return self._response_code
 
     def get_selected_object(self):
+        """
+        Gets the object selected using the object chooser.
+
+        Returns:
+            object, the object selected
+        """
         if self._object_id is None:
             return None
         else:
             return datastore.get(self._object_id)
 
     def destroy(self):
+        """
+        Destroys and cleans up (disposes) the object chooser.
+        """
         self._cleanup()
 
     def _cleanup(self):