More doc-string refactoring

src/groupchat_control.py

@@ -64,7 +64,9 @@ C_AVATAR, # avatar of the contact
 ) = range(5)
 
 def set_renderer_color(treeview, renderer, set_background=True):
-	'''set style for group row, using PRELIGHT system color'''
+	"""
+	Set style for group row, using PRELIGHT system color
+	"""
 	if set_background:
 		bgcolor = treeview.style.bg[gtk.STATE_PRELIGHT]
 		renderer.set_property('cell-background-gdk', bgcolor)
@@ -141,7 +143,9 @@ class PrivateChatControl(ChatControl):
 		self.TYPE_ID = 'pm'
 
 	def send_message(self, message, xhtml=None, process_commands=True):
-		'''call this function to send our message'''
+		"""
+		Call this method to send the message
+		"""
 		if not message:
 			return
 
@@ -383,7 +387,9 @@ class GroupchatControl(ChatControlBase):
 		self.widget.show_all()
 
 	def tree_compare_iters(self, model, iter1, iter2):
-		'''Compare two iters to sort them'''
+		"""
+		Compare two iters to sort them
+		"""
 		type1 = model[iter1][C_TYPE]
 		type2 = model[iter2][C_TYPE]
 		if not type1 or not type2:
@@ -422,8 +428,10 @@ class GroupchatControl(ChatControlBase):
 		return locale.strcoll(name1.lower(), name2.lower())
 
 	def on_msg_textview_populate_popup(self, textview, menu):
-		'''we override the default context menu and we prepend Clear
+		"""
-		and the ability to insert a nick'''
+		Override the default context menu and we prepend Clear
+		and the ability to insert a nick
+		"""
 		ChatControlBase.on_msg_textview_populate_popup(self, textview, menu)
 		item = gtk.SeparatorMenuItem()
 		menu.prepend(item)
@@ -452,7 +460,9 @@ class GroupchatControl(ChatControlBase):
 		gobject.idle_add(reset_flag)
 
 	def on_treeview_size_allocate(self, widget, allocation):
-		'''The MUC treeview has resized. Move the hpaned in all tabs to match'''
+		"""
+		The MUC treeview has resized. Move the hpaned in all tabs to match
+		"""
 		if self.resize_from_another_muc:
 			# Don't send the event to other MUC
 			return
@@ -467,7 +477,9 @@ class GroupchatControl(ChatControlBase):
 					ctrl.resize_occupant_treeview(hpaned_position)
 
 	def iter_contact_rows(self):
-		'''iterate over all contact rows in the tree model'''
+		"""
+		Iterate over all contact rows in the tree model
+		"""
 		model = self.list_treeview.get_model()
 		role_iter = model.get_iter_root()
 		while role_iter:
@@ -478,7 +490,9 @@ class GroupchatControl(ChatControlBase):
 			role_iter = model.iter_next(role_iter)
 
 	def on_list_treeview_style_set(self, treeview, style):
-		'''When style (theme) changes, redraw all contacts'''
+		"""
+		When style (theme) changes, redraw all contacts
+		"""
 		# Get the room_jid from treeview
 		for contact in self.iter_contact_rows():
 			nick = contact[C_NICK].decode('utf-8')
@@ -500,10 +514,11 @@ class GroupchatControl(ChatControlBase):
 		self.draw_contact(nick, selected=True, focus=True)
 
 	def get_tab_label(self, chatstate):
-		'''Markup the label if necessary. Returns a tuple such as:
+		"""
-		(new_label_str, color)
+		Markup the label if necessary. Returns a tuple such as: (new_label_str,
-		either of which can be None
+		color) either of which can be None if chatstate is given that means we
-		if chatstate is given that means we have HE SENT US a chatstate'''
+		have HE SENT US a chatstate
+		"""
 
 		has_focus = self.parent_win.window.get_property('has-toplevel-focus')
 		current_tab = self.parent_win.get_active_control() == self
@@ -588,10 +603,10 @@ class GroupchatControl(ChatControlBase):
 		banner_status_img.set_from_pixbuf(scaled_pix)
 
 	def get_continued_conversation_name(self):
-		'''Get the name of a continued conversation.
+		"""
-		Will return Continued Conversation if there isn't any other
+		Get the name of a continued conversation.  Will return Continued
-		contact in the room
+		Conversation if there isn't any other contact in the room
-		'''
+		"""
 		nicks = []
 		for nick in gajim.contacts.get_nick_list(self.account,
 		self.room_jid):
@@ -605,9 +620,10 @@ class GroupchatControl(ChatControlBase):
 		return title
 
 	def draw_banner_text(self):
-		'''Draw the text in the fat line at the top of the window that
+		"""
-		houses the room jid, subject.
+		Draw the text in the fat line at the top of the window that houses the
-		'''
+		room jid, subject
+		"""
 		self.name_label.set_ellipsize(pango.ELLIPSIZE_END)
 		self.banner_status_label.set_ellipsize(pango.ELLIPSIZE_END)
 		font_attrs, font_attrs_small = self.get_font_attrs()
@@ -641,7 +657,9 @@ class GroupchatControl(ChatControlBase):
 		self.banner_status_label.set_markup(subject_text)
 
 	def prepare_context_menu(self, hide_buttonbar_items=False):
-		'''sets sensitivity state for configure_room'''
+		"""
+		Set sensitivity state for configure_room
+		"""
 		xml = gtkgui_helpers.get_glade('gc_control_popup_menu.glade')
 		menu = xml.get_widget('gc_control_popup_menu')
 
@@ -776,8 +794,8 @@ class GroupchatControl(ChatControlBase):
 			else:
 				self.print_conversation(msg, nick, tim, xhtml)
 
-	def on_private_message(self, nick, msg, tim, xhtml, session,
+	def on_private_message(self, nick, msg, tim, xhtml, session, msg_id=None,
-	msg_id=None, encrypted=False):
+			encrypted=False):
 		# Do we have a queue?
 		fjid = self.room_jid + '/' + nick
 		no_queue = len(gajim.events.get_events(self.account, fjid)) == 0
@@ -835,8 +853,7 @@ class GroupchatControl(ChatControlBase):
 				fin = True
 		return None
 
-	def print_old_conversation(self, text, contact='', tim=None,
+	def print_old_conversation(self, text, contact='', tim=None, xhtml = None):
-	xhtml = None):
 		if isinstance(text, str):
 			text = unicode(text, 'utf-8')
 		if contact:
@@ -856,10 +873,13 @@ class GroupchatControl(ChatControlBase):
 
 	def print_conversation(self, text, contact='', tim=None, xhtml=None,
 			graphics=True):
-		'''Print a line in the conversation:
+		"""
-		if contact is set: it's a message from someone or an info message (contact
+		Print a line in the conversation
-		= 'info' in such a case)
+
-		if contact is not set: it's a message from the server or help'''
+		If contact is set: it's a message from someone or an info message
+		(contact = 'info' in such a case).
+		If contact is not set: it's a message from the server or help.
+		"""
 		if isinstance(text, str):
 			text = unicode(text, 'utf-8')
 		other_tags_for_name = []
@@ -938,8 +958,10 @@ class GroupchatControl(ChatControlBase):
 		return nb
 
 	def highlighting_for_message(self, text, tim):
-		'''Returns a 2-Tuple. The first says whether or not to highlight the
+		"""
-		text, the second, what sound to play.'''
+		Returns a 2-Tuple. The first says whether or not to highlight the text,
+		the second, what sound to play
+		"""
 		highlight, sound = (None, None)
 
 		# Are any of the defined highlighting words in the text?
@@ -961,10 +983,11 @@ class GroupchatControl(ChatControlBase):
 		return (highlight, sound)
 
 	def check_and_possibly_add_focus_out_line(self):
-		'''checks and possibly adds focus out line for room_jid if it needs it
+		"""
-		and does not already have it as last event. If it goes to add this line
+		Check and possibly add focus out line for room_jid if it needs it and
-		it removes previous line first'''
+		does not already have it as last event. If it goes to add this line
-
+		- remove previous line first
+		"""
 		win = gajim.interface.msg_win_mgr.get_window(self.room_jid, self.account)
 		if win and self.room_jid == win.get_active_jid() and\
 		win.window.get_property('has-toplevel-focus') and\
@@ -976,9 +999,10 @@ class GroupchatControl(ChatControlBase):
 		self.conv_textview.show_focus_out_line()
 
 	def needs_visual_notification(self, text):
-		'''checks text to see whether any of the words in (muc_highlight_words
+		"""
-		and nick) appear.'''
+		Check text to see whether any of the words in (muc_highlight_words and
-
+		nick) appear
+		"""
 		special_words = gajim.config.get('muc_highlight_words').split(';')
 		special_words.append(self.nick)
 		# Strip empties: ''.split(';') == [''] and would highlight everything.
@@ -1073,8 +1097,10 @@ class GroupchatControl(ChatControlBase):
 
 	def on_send_pm(self, widget=None, model=None, iter_=None, nick=None,
 			msg=None):
-		'''opens a chat window and if msg is not None sends private message to a
+		"""
-		contact in a room'''
+		Open a chat window and if msg is not None - send private message to a
+		contact in a room
+		"""
 		if nick is None:
 			nick = model[iter_][C_NICK].decode('utf-8')
 
@@ -1083,7 +1109,9 @@ class GroupchatControl(ChatControlBase):
 			ctrl.send_message(msg)
 
 	def on_send_file(self, widget, gc_contact):
-		'''sends a file to a contact in the room'''
+		"""
+		Send a file to a contact in the room
+		"""
 		self._on_send_file(gc_contact)
 
 	def draw_contact(self, nick, selected=False, focus=False):
@@ -1169,7 +1197,9 @@ class GroupchatControl(ChatControlBase):
 
 	def chg_contact_status(self, nick, show, status, role, affiliation, jid,
 			reason, actor, statusCode, new_nick, avatar_sha, tim=None):
-		'''When an occupant changes his or her status'''
+		"""
+		When an occupant changes his or her status
+		"""
 		if show == 'invisible':
 			return
 
@@ -1514,7 +1544,9 @@ class GroupchatControl(ChatControlBase):
 		return None
 
 	def remove_contact(self, nick):
-		'''Remove a user from the contacts_list'''
+		"""
+		Remove a user from the contacts_list
+		"""
 		model = self.list_treeview.get_model()
 		iter_ = self.get_contact_iter(nick)
 		if not iter_:
@@ -1529,7 +1561,9 @@ class GroupchatControl(ChatControlBase):
 			model.remove(parent_iter)
 
 	def send_message(self, message, xhtml=None, process_commands=True):
-		'''call this function to send our message'''
+		"""
+		Call this function to send our message
+		"""
 		if not message:
 			return
 
@@ -1752,7 +1786,9 @@ class GroupchatControl(ChatControlBase):
 			_('You may also enter an alternate venue:'), ok_handler=on_ok)
 
 	def _on_bookmark_room_menuitem_activate(self, widget):
-		'''bookmark the room, without autojoin and not minimized'''
+		"""
+		Bookmark the room, without autojoin and not minimized
+		"""
 		password = gajim.gc_passwords.get(self.room_jid, '')
 		gajim.interface.add_gc_bookmark(self.account, self.name, self.room_jid, \
 			'0', '0', password, self.nick)
@@ -1904,19 +1940,25 @@ class GroupchatControl(ChatControlBase):
 				return True
 
 	def on_list_treeview_row_expanded(self, widget, iter_, path):
-		'''When a row is expanded: change the icon of the arrow'''
+		"""
+		When a row is expanded: change the icon of the arrow
+		"""
 		model = widget.get_model()
 		image = gajim.interface.jabber_state_images['16']['opened']
 		model[iter_][C_IMG] = image
 
 	def on_list_treeview_row_collapsed(self, widget, iter_, path):
-		'''When a row is collapsed: change the icon of the arrow'''
+		"""
+		When a row is collapsed: change the icon of the arrow
+		"""
 		model = widget.get_model()
 		image = gajim.interface.jabber_state_images['16']['closed']
 		model[iter_][C_IMG] = image
 
 	def kick(self, widget, nick):
-		'''kick a user'''
+		"""
+		Kick a user
+		"""
 		def on_ok(reason):
 			gajim.connections[self.account].gc_set_role(self.room_jid, nick,
 				'none', reason)
@@ -1926,7 +1968,9 @@ class GroupchatControl(ChatControlBase):
 					_('You may specify a reason below:'), ok_handler=on_ok)
 
 	def mk_menu(self, event, iter_):
-		'''Make contact's popup menu'''
+		"""
+		Make contact's popup menu
+		"""
 		model = self.list_treeview.get_model()
 		nick = model[iter_][C_NICK].decode('utf-8')
 		c = gajim.contacts.get_gc_contact(self.account, self.room_jid, nick)
@@ -2070,8 +2114,10 @@ class GroupchatControl(ChatControlBase):
 		return ctrl
 
 	def on_row_activated(self, widget, path):
-		'''When an iter is activated (dubblick or single click if gnome is set
+		"""
-		this way'''
+		When an iter is activated (dubblick or single click if gnome is set this
+		way
+		"""
 		model = widget.get_model()
 		if len(path) == 1: # It's a group
 			if (widget.row_expanded(path)):
@@ -2083,12 +2129,16 @@ class GroupchatControl(ChatControlBase):
 			self._start_private_message(nick)
 
 	def on_list_treeview_row_activated(self, widget, path, col=0):
-		'''When an iter is double clicked: open the chat window'''
+		"""
+		When an iter is double clicked: open the chat window
+		"""
 		if not gajim.single_click:
 			self.on_row_activated(widget, path)
 
 	def on_list_treeview_button_press_event(self, widget, event):
-		'''popup user's group's or agent menu'''
+		"""
+		Popup user's group's or agent menu
+		"""
 		# hide tooltip, no matter the button is pressed
 		self.tooltip.hide_tooltip()
 		try:
@@ -2199,27 +2249,37 @@ class GroupchatControl(ChatControlBase):
 			self.tooltip.hide_tooltip()
 
 	def grant_voice(self, widget, nick):
-		'''grant voice privilege to a user'''
+		"""
+		Grant voice privilege to a user
+		"""
 		gajim.connections[self.account].gc_set_role(self.room_jid, nick,
 			'participant')
 
 	def revoke_voice(self, widget, nick):
-		'''revoke voice privilege to a user'''
+		"""
+		Revoke voice privilege to a user
+		"""
 		gajim.connections[self.account].gc_set_role(self.room_jid, nick,
 			'visitor')
 
 	def grant_moderator(self, widget, nick):
-		'''grant moderator privilege to a user'''
+		"""
+		Grant moderator privilege to a user
+		"""
 		gajim.connections[self.account].gc_set_role(self.room_jid, nick,
 			'moderator')
 
 	def revoke_moderator(self, widget, nick):
-		'''revoke moderator privilege to a user'''
+		"""
+		Revoke moderator privilege to a user
+		"""
 		gajim.connections[self.account].gc_set_role(self.room_jid, nick,
 			'participant')
 
 	def ban(self, widget, jid):
-		'''ban a user'''
+		"""
+		Ban a user
+		"""
 		def on_ok(reason):
 			gajim.connections[self.account].gc_set_affiliation(self.room_jid, jid,
 				'outcast', reason)
@@ -2231,32 +2291,44 @@ class GroupchatControl(ChatControlBase):
 			_('You may specify a reason below:'), ok_handler=on_ok)
 
 	def grant_membership(self, widget, jid):
-		'''grant membership privilege to a user'''
+		"""
+		Grant membership privilege to a user
+		"""
 		gajim.connections[self.account].gc_set_affiliation(self.room_jid, jid,
 			'member')
 
 	def revoke_membership(self, widget, jid):
-		'''revoke membership privilege to a user'''
+		"""
+		Revoke membership privilege to a user
+		"""
 		gajim.connections[self.account].gc_set_affiliation(self.room_jid, jid,
 			'none')
 
 	def grant_admin(self, widget, jid):
-		'''grant administrative privilege to a user'''
+		"""
+		Grant administrative privilege to a user
+		"""
 		gajim.connections[self.account].gc_set_affiliation(self.room_jid, jid,
 			'admin')
 
 	def revoke_admin(self, widget, jid):
-		'''revoke administrative privilege to a user'''
+		"""
+		Revoke administrative privilege to a user
+		"""
 		gajim.connections[self.account].gc_set_affiliation(self.room_jid, jid,
 			'member')
 
 	def grant_owner(self, widget, jid):
-		'''grant owner privilege to a user'''
+		"""
+		Grant owner privilege to a user
+		"""
 		gajim.connections[self.account].gc_set_affiliation(self.room_jid, jid,
 			'owner')
 
 	def revoke_owner(self, widget, jid):
-		'''revoke owner privilege to a user'''
+		"""
+		Revoke owner privilege to a user
+		"""
 		gajim.connections[self.account].gc_set_affiliation(self.room_jid, jid,
 			'admin')