Fix formatting, some typos, and unused code, and add docstrings

- No idea why subclasses of ConversationTab were working before
    (info_header was overriden with None in __init__)
- Or why the date parsing worked (“Exeception”)
- Some more reformatting with pylint indications
- Document each module in the tabs module

7 files changed, 110 insertions, 33 deletions

diff --git a/src/tabs/basetabs.py b/src/tabs/basetabs.py
index 86ba9e1f..5e38775b 100644
--- a/src/tabs/basetabs.py
+++ b/src/tabs/basetabs.py
@@ -1,9 +1,16 @@
 """
-A Tab object is a way to organize various Windows (see windows.py)
-around the screen at once.
-A tab is then composed of multiple Buffers.
-Each Tab object has different refresh() and resize() methods, defining how its
-Windows are displayed, resized, etc.
+Module for the base Tabs
+
+The root class Tab defines the generic interface and attributes of a
+tab. A tab organizes various Windows around the screen depending
+of the tab specificity. If the tab shows messages, it will also
+reference a buffer containing the messages.
+
+Each subclass should redefine its own refresh() and resize() method
+according to its windows.
+
+This module also defines ChatTabs, the parent class for all tabs
+revolving around chats.
 """
 
 from gettext import gettext as _
@@ -33,6 +40,7 @@ from theming import get_theme
 MIN_WIDTH = 42
 MIN_HEIGHT = 6
 
+# getters for tab colors (lambdas, so that they are dynamic)
 STATE_COLORS = {
         'disconnected': lambda: get_theme().COLOR_TAB_DISCONNECTED,
         'scrolled': lambda: get_theme().COLOR_TAB_SCROLLED,
@@ -44,7 +52,6 @@ STATE_COLORS = {
         'current': lambda: get_theme().COLOR_TAB_CURRENT,
         'attention': lambda: get_theme().COLOR_TAB_ATTENTION,
     }
-
 VERTICAL_STATE_COLORS = {
         'disconnected': lambda: get_theme().COLOR_VERTICAL_TAB_DISCONNECTED,
         'scrolled': lambda: get_theme().COLOR_VERTICAL_TAB_SCROLLED,
@@ -58,6 +65,8 @@ VERTICAL_STATE_COLORS = {
     }
 
 
+# priority of the different tab states when using Alt+e
+# higher means more priority, < 0 means not selectable
 STATE_PRIORITY = {
         'normal': -1,
         'current': -1,
@@ -465,7 +474,7 @@ class ChatTab(Tab):
                 identifier=identifier,
                 jid=jid)
 
-    def modify_message(self, txt, old_id, new_id, user=None,jid=None, nickname=None):
+    def modify_message(self, txt, old_id, new_id, user=None, jid=None, nickname=None):
         self.log_message(txt, nickname, typ=1)
         message = self._text_buffer.modify_message(txt, old_id, new_id, time=time, user=user, jid=jid)
         if message:
@@ -663,4 +672,3 @@ class ChatTab(Tab):
     def scroll_separator(self):
         self.text_win.scroll_to_separator()
 
-
diff --git a/src/tabs/conversationtab.py b/src/tabs/conversationtab.py
index 143c8d68..64eeb4bf 100644
--- a/src/tabs/conversationtab.py
+++ b/src/tabs/conversationtab.py
@@ -1,3 +1,16 @@
+"""
+Module for the ConversationTabs
+
+A ConversationTab is a direct chat between two JIDs, outside of a room.
+
+There are two different instances of a ConversationTab:
+- A DynamicConversationTab that implements XEP-0296 (best practices for
+    resource locking), which means it will switch the resource it is
+    focused on depending on the presences received. This is the default.
+- A StaticConversationTab that will stay focused on one resource all
+    the time.
+
+"""
 from gettext import gettext as _
 
 import logging
@@ -212,7 +225,10 @@ class ConversationTab(ChatTab):
         if 'urn:xmpp:attention:0' in iq['disco_info'].get_features():
             self.core.information('Attention is supported', 'Info')
             self.remote_supports_attention = True
-            self.commands['attention'] =  (self.command_attention, _('Usage: /attention [message]\nAttention: Require the attention of the contact. Can also send a message along with the attention.'), None)
+            self.commands['attention'] = (self.command_attention,
+                    _('Usage: /attention [message]\nAttention: Require'
+                      ' the attention of the contact. Can also send a '
+                      'message along with the attention.'), None)
         else:
             self.remote_supports_attention = False
 
@@ -238,7 +254,8 @@ class ConversationTab(ChatTab):
             if jid in roster:
                 resource = roster[jid].get_highest_priority_resource()
                 jid = resource.jid if resource else jid
-        fixes.get_version(self.core.xmpp, jid, callback=callback)
+        fixes.get_version(self.core.xmpp, jid,
+                callback=callback)
 
     def resize(self):
         if self.core.information_win_size >= self.height-3 or not self.visible:
@@ -253,7 +270,7 @@ class ConversationTab(ChatTab):
     def refresh(self):
         if self.need_resize:
             self.resize()
-        log.debug('  TAB   Refresh: %s',self.__class__.__name__)
+        log.debug('  TAB   Refresh: %s', self.__class__.__name__)
         self.text_win.refresh()
         self.upper_bar.refresh(self.get_dest_jid(), roster[self.get_dest_jid()])
         self.info_header.refresh(self.get_dest_jid(), roster[self.get_dest_jid()], self.text_win, self.chatstate, ConversationTab.additional_informations)
@@ -396,7 +413,7 @@ class DynamicConversationTab(ConversationTab):
         """
         if self.need_resize:
             self.resize()
-        log.debug('  TAB   Refresh: %s',self.__class__.__name__)
+        log.debug('  TAB   Refresh: %s', self.__class__.__name__)
         self.text_win.refresh()
         self.upper_bar.refresh(self.get_name(), roster[self.get_name()])
         if self.locked_resource:
diff --git a/src/tabs/muclisttab.py b/src/tabs/muclisttab.py
index 0fe27307..c5b2a205 100644
--- a/src/tabs/muclisttab.py
+++ b/src/tabs/muclisttab.py
@@ -1,3 +1,9 @@
+"""
+A MucListTab is a tab listing the rooms on a conference server.
+
+It has no functionnality except scrolling the list, and allowing the
+user to join the rooms.
+"""
 from gettext import gettext as _
 
 import logging
@@ -18,6 +24,7 @@ class MucListTab(Tab):
     """
     plugin_commands = {}
     plugin_keys = {}
+
     def __init__(self, server):
         Tab.__init__(self)
         self.state = 'normal'
@@ -47,7 +54,7 @@ class MucListTab(Tab):
     def refresh(self):
         if self.need_resize:
             self.resize()
-        log.debug('  TAB   Refresh: %s',self.__class__.__name__)
+        log.debug('  TAB   Refresh: %s', self.__class__.__name__)
         self.info_header.refresh()
         self.info_win.refresh()
         self.refresh_tab_win()
@@ -61,7 +68,7 @@ class MucListTab(Tab):
             return
         self.need_resize = False
         self.info_header.resize(1, self.width, self.height-2-self.core.information_win_size - Tab.tab_win_height(), 0)
-        column_size = {'node-part': int(self.width*2/8) ,
+        column_size = {'node-part': int(self.width*2/8),
                        'name': int(self.width*5/8),
                        'users': self.width-int(self.width*2/8)-int(self.width*5/8)}
         self.list_header.resize_columns(column_size)
@@ -105,7 +112,7 @@ class MucListTab(Tab):
             return
         items = [{'node-part': safeJID(item[0]).user if safeJID(item[0]).server == self.name else safeJID(item[0]).bare,
                   'jid': item[0],
-                  'name': item[2] or '' ,'users': ''} for item in iq['disco_items'].get_items()]
+                  'name': item[2] or '', 'users': ''} for item in iq['disco_items'].get_items()]
         self.listview.add_lines(items)
         self.info_header.message = _('Chatroom list on server %s') % self.name
         if self.core.current_tab() is self:
@@ -118,11 +125,15 @@ class MucListTab(Tab):
 
     def sort_by(self):
         if self.list_header.get_order():
-            self.listview.sort_by_column(col_name=self.list_header.get_sel_column(),asc=False)
+            self.listview.sort_by_column(
+                    col_name=self.list_header.get_sel_column(),
+                    asc=False)
             self.list_header.set_order(False)
             self.list_header.refresh()
         else:
-            self.listview.sort_by_column(col_name=self.list_header.get_sel_column(),asc=True)
+            self.listview.sort_by_column(
+                    col_name=self.list_header.get_sel_column(),
+                    asc=True)
             self.list_header.set_order(True)
             self.list_header.refresh()
         curses.doupdate()
diff --git a/src/tabs/muctab.py b/src/tabs/muctab.py
index 9bc2f88e..0b56df35 100644
--- a/src/tabs/muctab.py
+++ b/src/tabs/muctab.py
@@ -1,3 +1,12 @@
+"""
+Module for the MucTab
+
+A MucTab is a tab for multi-user chats as defined in XEP-0045.
+
+It keeps track of many things such as part/joins, maintains an
+user list, and updates private tabs when necessary.
+"""
+
 from gettext import gettext as _
 
 import logging
@@ -250,7 +259,7 @@ class MucTab(ChatTab):
             return the_input.new_completion(userlist, 1, '', quotify=True)
         elif n == 2:
             possible_affiliations = ['none', 'member', 'admin', 'owner', 'outcast']
-            return the_input.new_completion(possible_affiliations, 2,  '', quotify=True)
+            return the_input.new_completion(possible_affiliations, 2, '', quotify=True)
 
     def command_invite(self, args):
         """/invite <jid> [reason]"""
@@ -368,7 +377,6 @@ class MucTab(ChatTab):
                          res.get('version') or _('unknown'),
                          res.get('os') or _('an unknown platform'))
             self.core.information(version, 'Info')
-
         if not arg:
             return self.core.command_help('version')
         if arg in [user.nick for user in self.users]:
@@ -376,7 +384,8 @@ class MucTab(ChatTab):
             jid = safeJID(jid + '/' + arg)
         else:
             jid = safeJID(arg)
-        fixes.get_version(self.core.xmpp, jid, callback=callback)
+        fixes.get_version(self.core.xmpp, jid,
+                callback=callback)
 
     def command_nick(self, arg):
         """
@@ -404,13 +413,13 @@ class MucTab(ChatTab):
             if arg:
                 msg = _("\x195}You left the chatroom (\x19o%s\x195})\x193}" % arg)
             else:
-                msg =_("\x195}You left the chatroom\x193}")
+                msg = _("\x195}You left the chatroom\x193}")
             self.add_message(msg, typ=2)
             if self == self.core.current_tab():
                 self.refresh()
             self.core.doupdate()
         else:
-            msg =_("\x195}You left the chatroom\x193}")
+            msg = _("\x195}You left the chatroom\x193}")
         self.core.disable_private_tabs(self.name, reason=msg)
 
     def command_close(self, arg):
@@ -484,16 +493,16 @@ class MucTab(ChatTab):
         buff = ['Users: %s \n' % len(self.users)]
         for moderator in moderators:
             buff.append('\x19%s}%s\x19o\x19%s}%s\x19o' % (color_moderator,
-                    moderator[1],  dump_tuple(moderator[0].color), moderator[0].nick))
+                    moderator[1], dump_tuple(moderator[0].color), moderator[0].nick))
         for participant in participants:
             buff.append('\x19%s}%s\x19o\x19%s}%s\x19o' % (color_participant,
-                    participant[1],  dump_tuple(participant[0].color), participant[0].nick))
+                    participant[1], dump_tuple(participant[0].color), participant[0].nick))
         for visitor in visitors:
             buff.append('\x19%s}%s\x19o\x19%s}%s\x19o' % (color_visitor,
-                    visitor[1],  dump_tuple(visitor[0].color), visitor[0].nick))
+                    visitor[1], dump_tuple(visitor[0].color), visitor[0].nick))
         for other in others:
             buff.append('\x19%s}%s\x19o\x19%s}%s\x19o' % (color_other,
-                    other[1],  dump_tuple(other[0].color), other[0].nick))
+                    other[1], dump_tuple(other[0].color), other[0].nick))
         buff.append('\n')
         message = ' '.join(buff)
 
@@ -563,7 +572,7 @@ class MucTab(ChatTab):
         if len(args) < 2:
             self.core.command_help('role')
             return
-        nick, role = args[0],args[1]
+        nick, role = args[0], args[1]
         if len(args) > 2:
             reason = ' '.join(args[2:])
         else:
@@ -704,7 +713,7 @@ class MucTab(ChatTab):
     def refresh(self):
         if self.need_resize:
             self.resize()
-        log.debug('  TAB   Refresh: %s',self.__class__.__name__)
+        log.debug('  TAB   Refresh: %s', self.__class__.__name__)
         self.topic_win.refresh(self.get_single_line_topic())
         self.text_win.refresh()
         if config.get("hide_user_list", "false") == "false":
diff --git a/src/tabs/privatetab.py b/src/tabs/privatetab.py
index 574a2218..6adbf878 100644
--- a/src/tabs/privatetab.py
+++ b/src/tabs/privatetab.py
@@ -1,3 +1,15 @@
+"""
+Module for the PrivateTab
+
+A PrivateTab is a private conversation opened with someone from a MUC
+(see muctab.py). The conversation happens with both JID being relative
+to the MUC (room@server/nick1 and room@server/nick2).
+
+This tab references his parent room, and is modified to keep track of
+both participant’s nicks. It also has slightly different features than
+the ConversationTab (such as tab-completion on nicks from the room).
+
+"""
 from gettext import gettext as _
 
 import logging
@@ -182,7 +194,12 @@ class PrivateTab(ChatTab):
         if 'urn:xmpp:attention:0' in iq['disco_info'].get_features():
             self.core.information('Attention is supported', 'Info')
             self.remote_supports_attention = True
-            self.commands['attention'] =  (self.command_attention, _('Usage: /attention [message]\nAttention: Require the attention of the contact. Can also send a message along with the attention.'), None)
+            self.commands['attention'] = (
+                    self.command_attention,
+                    _('Usage: /attention [message]\nAttention:'
+                      'Require the attention of the contact. Can'
+                      ' also send a message along with the attention.'),
+                    None)
         else:
             self.remote_supports_attention = False
 
@@ -207,7 +224,8 @@ class PrivateTab(ChatTab):
         if arg:
             return self.core.command_version(arg)
         jid = safeJID(self.name)
-        fixes.get_version(self.core.xmpp, jid, callback=callback)
+        fixes.get_version(self.core.xmpp, jid,
+                callback=callback)
 
     def command_info(self, arg):
         """
@@ -231,7 +249,7 @@ class PrivateTab(ChatTab):
     def refresh(self):
         if self.need_resize:
             self.resize()
-        log.debug('  TAB   Refresh: %s',self.__class__.__name__)
+        log.debug('  TAB   Refresh: %s', self.__class__.__name__)
         self.text_win.refresh()
         self.info_header.refresh(self.name, self.text_win, self.chatstate, PrivateTab.additional_informations)
         self.info_win.refresh()
diff --git a/src/tabs/rostertab.py b/src/tabs/rostertab.py
index 2ab81dae..22cad8b9 100644
--- a/src/tabs/rostertab.py
+++ b/src/tabs/rostertab.py
@@ -1,3 +1,10 @@
+"""
+The RosterInfoTab is the tab showing roster info, the list of contacts,
+half of it is dedicated to showing the information buffer, and a small
+rectangle shows the current contact info.
+
+This module also includes functions to match users in the roster.
+"""
 from gettext import gettext as _
 
 import logging
@@ -690,7 +697,7 @@ class RosterInfoTab(Tab):
     def refresh(self):
         if self.need_resize:
             self.resize()
-        log.debug('  TAB   Refresh: %s',self.__class__.__name__)
+        log.debug('  TAB   Refresh: %s', self.__class__.__name__)
         self.v_separator.refresh()
         self.roster_win.refresh(roster)
         self.contact_info_win.refresh(self.roster_win.get_selected_row())
diff --git a/src/tabs/xmltab.py b/src/tabs/xmltab.py
index ed099405..a2728586 100644
--- a/src/tabs/xmltab.py
+++ b/src/tabs/xmltab.py
@@ -1,3 +1,10 @@
+"""
+The XMLTab is here for debugging purposes, it shows the incoming and
+outgoing stanzas. It has a few useful functions that can filter stanzas
+in order to only show the relevant ones, and it can also be frozen or
+unfrozen on demand so that the relevant information is not drowned by
+the traffic.
+"""
 from gettext import gettext as _
 
 import logging
@@ -168,7 +175,7 @@ class XMLTab(Tab):
     def refresh(self):
         if self.need_resize:
             self.resize()
-        log.debug('  TAB   Refresh: %s',self.__class__.__name__)
+        log.debug('  TAB   Refresh: %s', self.__class__.__name__)
         self.text_win.refresh()
         self.info_header.refresh(self.filter_type, self.filter, self.text_win)
         self.refresh_tab_win()