changeset 617:5baca9d46c34 frontends_multi_profiles

browser_side: add/improve some docstrings
author souliane <souliane@mailoo.org>
date Wed, 11 Feb 2015 11:21:27 +0100 (2015-02-11)
parents 1c0d5a87c554
children 698bdb84f6a7 57a651a5b31d
files src/browser/sat_browser/base_widget.py src/browser/sat_browser/blog.py src/browser/sat_browser/chat.py src/browser/sat_browser/contact_list.py
diffstat 4 files changed, 51 insertions(+), 21 deletions(-) [+]
line wrap: on
line diff
--- a/src/browser/sat_browser/base_widget.py	Wed Feb 11 11:18:13 2015 +0100
+++ b/src/browser/sat_browser/base_widget.py	Wed Feb 11 11:21:27 2015 +0100
@@ -210,6 +210,14 @@
     ITEM_TPL = "<img src='media/icons/misc/%s.png' />"
 
     def __init__(self, parent, host, vertical=False, styles=None):
+        """
+
+        @param parent (Widget): LiberviaWidget, or instance of another class
+            implementing the method addMenus
+        @param host (SatWebFrontend)
+        @param vertical (bool): if True, set the menu vertically
+        @param styles (dict): optional styles dict
+        """
         menu_styles = {'menu_bar': 'widgetHeader_buttonGroup'}
         if styles:
             menu_styles.update(styles)
@@ -230,6 +238,11 @@
 class WidgetSubMenuBar(base_menu.GenericMenuBar):
 
     def __init__(self, host, vertical=True):
+        """
+
+        @param host (SatWebFrontend)
+        @param vertical (bool): if True, set the menu vertically
+        """
         base_menu.GenericMenuBar.__init__(self, host, vertical=vertical, flat_level=1)
 
     @classmethod
@@ -802,7 +815,10 @@
         Window.addWindowResizeListener(self)
 
     def getCurrentPanel(self):
-        """ Get the panel of the currently selected tab """
+        """ Get the panel of the currently selected tab
+
+        @return: WidgetsPanel
+        """
         return self.deck.visibleWidget
 
     def onWindowResized(self, width, height):
--- a/src/browser/sat_browser/blog.py	Wed Feb 11 11:18:13 2015 +0100
+++ b/src/browser/sat_browser/blog.py	Wed Feb 11 11:21:27 2015 +0100
@@ -437,7 +437,7 @@
     def onGroupDrop(host, item):
         """Generic panel creation for one, several or all groups (meta).
 
-        @parem host: the SatWebFrontend instance
+        @param host (SatWebFrontend): the SatWebFrontend instance
         @param item: single group as a string, list of groups
          (as an array) or None (for the meta group = "all groups")
         @return: the created MicroblogPanel
--- a/src/browser/sat_browser/chat.py	Wed Feb 11 11:18:13 2015 +0100
+++ b/src/browser/sat_browser/chat.py	Wed Feb 11 11:21:27 2015 +0100
@@ -337,7 +337,7 @@
         self.state_machine.started = not not state  # start to send "composing" state from now
 
     def refreshTitle(self):
-        """Refresh the title of this ChatPanel dialog"""
+        """Refresh the title of this Chat dialog"""
         if self._state:
             self.setTitle(self.target.bare + " (" + self._state + ")")
         else:
--- a/src/browser/sat_browser/contact_list.py	Wed Feb 11 11:18:13 2015 +0100
+++ b/src/browser/sat_browser/contact_list.py	Wed Feb 11 11:21:27 2015 +0100
@@ -45,9 +45,10 @@
 
 def buildPresenceStyle(presence, base_style=None):
     """Return the CSS classname to be used for displaying the given presence information.
-    @param presence (str): presence is a value in ('', 'chat', 'away', 'dnd', 'xa')
-    @param base_style (str): base classname
-    @return: str
+
+    @param presence (unicode): presence is a value in ('', 'chat', 'away', 'dnd', 'xa')
+    @param base_style (unicode): base classname
+    @return: unicode
     """
     if not base_style:
         base_style = "contactLabel"
@@ -59,8 +60,8 @@
     Set the CSS style of a contact's element according to its presence.
 
     @param widget (Widget): the UI element of the contact
-    @param presence (str): a value in ("", "chat", "away", "dnd", "xa").
-    @param base_style (str): the base name of the style to apply
+    @param presence (unicode): a value in ("", "chat", "away", "dnd", "xa").
+    @param base_style (unicode): the base name of the style to apply
     """
     if not hasattr(widget, 'presence_style'):
         widget.presence_style = None
@@ -75,6 +76,11 @@
 
 class GroupLabel(base_widget.DragLabel, Label, ClickHandler):
     def __init__(self, host, group):
+        """
+
+        @param host (SatWebFrontend)
+        @param group (unicode): group name
+        """
         self.group = group
         Label.__init__(self, group)  # , Element=DOM.createElement('div')
         self.setStyleName('group')
@@ -87,9 +93,9 @@
 
 
 class ContactLabel(HTML):
-    def __init__(self, jid, name=None):
+    def __init__(self, jid_, name=None):
         HTML.__init__(self)
-        self.name = name or str(jid)
+        self.name = name or unicode(jid_)
         self.waiting = False
         self.refresh()
         self.setStyleName('contactLabel')
@@ -126,6 +132,14 @@
 class ContactBox(VerticalPanel, ClickHandler, base_widget.DragLabel):
 
     def __init__(self, host, jid_, name=None, click_listener=None, handle_menu=None):
+        """
+
+        @param host (SatWebFrontend)
+        @param jid_ (jid.JID): contact JID
+        @param name (unicode): contact alias
+        @param click_listener (callable): click callback
+        @param handle_menu (bool): if True, bind a popup menu to the avatar
+        """
         VerticalPanel.__init__(self, StyleName='contactBox', VerticalAlignment='middle')
         base_widget.DragLabel.__init__(self, jid_, "CONTACT", host)
         self.jid = jid_
@@ -152,7 +166,7 @@
     def updateAvatar(self, url):
         """Update the avatar.
 
-        @param url (str): image url
+        @param url (unicode): image url
         """
         self.avatar.setUrl(url)
 
@@ -194,7 +208,7 @@
     def getGroupBox(self, group):
         """get the widget of a group
 
-        @param group (str): the group
+        @param group (unicode): the group
         @return: GroupLabel instance if present, else None"""
         for wid in self:
             if isinstance(wid, GroupLabel) and wid.group == group:
@@ -226,7 +240,7 @@
         """Add a contact to the list.
 
         @param jid_ (jid.JID): jid_ of the contact
-        @param name (str): optional name of the contact
+        @param name (unicode): optional name of the contact
         """
         assert isinstance(jid_, jid.JID)
         if jid_ in self.contacts:
@@ -269,7 +283,7 @@
         """Update the avatar of the given contact
 
         @param jid_ (jid.JID): contact jid
-        @param url (str): image url
+        @param url (unicode): image url
         """
         try:
             self.getContactBox(jid_).updateAvatar(url)
@@ -286,7 +300,7 @@
     def setState(self, jid_, type_, state):
         """Change the appearance of the contact, according to the state
         @param jid_ (jid.JID): jid.JID which need to change state
-        @param type_ (str): one of "availability", "messageWaiting"
+        @param type_ (unicode): one of "availability", "messageWaiting"
         @param state:
             - for messageWaiting type:
                 True if message are waiting
@@ -431,7 +445,7 @@
 
     # def setConnected(self, jid_s, resource, availability, priority, statuses):
     #     """Set connection status
-    #     @param jid_s (str): JID userhost as unicode
+    #     @param jid_s (unicode): JID userhost as unicode
     #     """
     #     if availability == 'unavailable':
     #         if jid_s in self.connected:
@@ -538,8 +552,8 @@
     def updateAvatar(self, jid_s, url):
         """Update the avatar of the given contact
 
-        @param jid_s (str): contact jid
-        @param url (str): image url
+        @param jid_s (unicode): contact jid
+        @param url (unicode): image url
         """
         self._contacts_panel.updateAvatar(jid_s, url)
 
@@ -555,7 +569,7 @@
     def hasVisibleMembers(self, group):
         """Tell if the given group actually has visible members
 
-        @param group (str): the group to check
+        @param group (unicode): the group to check
         @return: boolean
         """
         for jid_ in self.groups[group]:
@@ -586,8 +600,8 @@
     # def updateVisibility(self, jids, groups):
     #     """Set the widgets visibility for the given contacts and groups
 
-    #     @param jids (list[str]): list of JID
-    #     @param groups (list[str]): list of groups
+    #     @param jids (list[unicode]): list of JID
+    #     @param groups (list[unicode]): list of groups
     #     """
     #     for jid_s in jids:
     #         try: