# HG changeset patch # User souliane # Date 1423650087 -3600 # Node ID 5baca9d46c3443907997fc2168168c0d98015dca # Parent 1c0d5a87c55437bb63f555c1da20860acf7be02b browser_side: add/improve some docstrings diff -r 1c0d5a87c554 -r 5baca9d46c34 src/browser/sat_browser/base_widget.py --- 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 = "" 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): diff -r 1c0d5a87c554 -r 5baca9d46c34 src/browser/sat_browser/blog.py --- 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 diff -r 1c0d5a87c554 -r 5baca9d46c34 src/browser/sat_browser/chat.py --- 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: diff -r 1c0d5a87c554 -r 5baca9d46c34 src/browser/sat_browser/contact_list.py --- 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: