From 2db9dee01ab0e12a6b53c0da844b285a9312cab1 Mon Sep 17 00:00:00 2001
From: Walter Bender <walter@sugarlabs.org>
Date: Sun, 12 May 2013 23:45:32 +0000
Subject: resync to latest version of patches submitted to sugar upstream on github

---
(limited to 'src/jarabe/web/account.py')

diff --git a/src/jarabe/web/account.py b/src/jarabe/web/account.py
index f9be23e..2e55f25 100644
--- a/src/jarabe/web/account.py
+++ b/src/jarabe/web/account.py
@@ -25,54 +25,119 @@ from sugar3.graphics.toolbutton import ToolButton
 
 class Account():
     ''' Account is a prototype class for online accounts. It provides
-    stubs for five public methods that are used by online services:
-
-    get_description returns a brief description of the online service
-    used in palette menuitems and on the webservices control panel.
-
-    is_configured returns True if the service has been configured for
-    use, e.g., an access token has been acquired.
-
-    is_active returns True if the service is currently available,
-    e.g., the access token has not expired.
-
-    get_share_menu returns a menu item used on the Copy To palette in
-    the Journal and on the Journal detail view toolbar.
-
-    get_refresh_menu returns a menu item used on the Journal detail
-    view toolbar.
+    stubs for five public methods that are used by online services
     '''
 
     def get_description(self):
+        ''' get_description returns a brief description of the online
+        service. The description is used in palette menuitems and on
+        the webservices control panel.
+
+        :returns: online-account name
+        :rtype: string
+        '''
         raise NotImplementedError
 
     def is_configured(self):
+        ''' is_configured returns True if the service has been
+        configured for use, e.g., an access token has been acquired.
+
+        :returns: configuration status
+        :rtype: bool
+        '''
         raise NotImplementedError
 
     def is_active(self):
+        ''' is_active returns True if the service is currently
+        available, e.g., the access token has not expired.
+
+        :returns: active status
+        :rtype: bool
+        '''
         raise NotImplementedError
 
     def get_share_menu(self):
+        ''' get_share_menu returns a menu item used on the Copy To
+        palette in the Journal and on the Journal detail-view toolbar.
+
+        :param: journal_entry_metadata
+        :type: dict
+        :returns: MenuItem
+        :rtype: MenuItem
+        '''
         raise NotImplementedError
 
     def get_refresh_menu(self):
+        ''' get_refresh_menu returns a menu item used on the Journal
+        detail-view toolbar.
+
+        :param: journal_entry_metadata
+        :type: dict
+        :returns: MenuItem
+        :rtype: MenuItem
+        '''
         raise NotImplementedError
 
 
 class MenuItem(MenuItem):
+    ''' This is a subclass of sugar3.graphics.menuitem.MenuItem
+
+    The transfer signals are used to update progress of data transfer
+    between Sugar and the online service. Signal handlers in the
+    journaltoolbox manage a Notification Alert of this progress.
+
+    'transfer-started' is emitted at the beginning of a transfer.
+
+    'transfer-progress' is emitted periodically to indicate progress.
+
+    :emits: total data to transfer
+    :type: float
+    :emits: quantity of data transfered
+    :type: float
+    :emits: message string
+    :type: string
+
+    'transfer-completed' is emitted at the successful completion of a
+    transfer.
+
+    :emits: message string
+    :type: string
+
+    'transfer-failed' is emitted at if the transfer fails.
+
+    :emits: message string
+    :type: string
+
+    'transfer-state-changed' is emitted when the account manager wants
+    to indicate a change in state.
+
+    :emits: message string
+    :type: string
+
+    The comments-changed signal is emitted by the online service if
+    changes to the 'comments' metadata have been made. The
+    expandedentry of the Journal detail view displays these comments.
+
+    :emits: metadata['comments']
+    :type: string
+    '''
     __gsignals__ = {
-        'transfer-started': (GObject.SignalFlags.RUN_FIRST, None,
-                             ([int, int])),
+        'transfer-started': (GObject.SignalFlags.RUN_FIRST, None, ([])),
         'transfer-progress': (GObject.SignalFlags.RUN_FIRST, None,
-                              ([int, int, float])),
-        'transfer-completed': (GObject.SignalFlags.RUN_FIRST, None,
-                               ([int, int])),
-        'transfer-failed': (GObject.SignalFlags.RUN_FIRST, None,
-                            ([int, int, str])),
+                              ([int, int, str])),
+        'transfer-completed': (GObject.SignalFlags.RUN_FIRST, None, ([str])),
+        'transfer-failed': (GObject.SignalFlags.RUN_FIRST, None, ([str])),
         'transfer-state-changed': (GObject.SignalFlags.RUN_FIRST, None,
                                    ([str])),
-        'comments-changed': (GObject.SignalFlags.RUN_FIRST, None, ([str])),
-    }
+        'comments-changed': (GObject.SignalFlags.RUN_FIRST, None, ([str]))
+        }
 
     def set_metadata(self, metadata):
+        ''' The online account uses this method to set metadata in the
+        Sugar journal and provide a means of updating menuitem status,
+        e.g., enabling the refresh menu after a successful transfer.
+
+        :param: journal_entry_metadata
+        :type: dict
+        '''
         raise NotImplementedError
--
cgit v0.9.1