Some comments added.

src/common/connection.py

@@ -87,7 +87,11 @@ class Connection(ConnectionHandlers):
 	def __init__(self, name):
 		ConnectionHandlers.__init__(self)
 		self.name = name
-		self.connected = 0 # offline
+		# self.connected:
+		# 0=>offline,
+		# 1=>connection in progress,
+		# 2=>authorised
+		self.connected = 0
 		self.connection = None # xmpppy ClientCommon instance
 		# this property is used to prevent double connections
 		self.last_connection = None # last ClientCommon instance
@@ -296,6 +300,8 @@ class Connection(ConnectionHandlers):
 				self.dispatch('STANZA_SENT', unicode(data))
 
 	def select_next_host(self, hosts):
+		'''Chooses best 'real' host basing on the SRV priority and weight data;
+		more info in RFC2782'''
 		hosts_best_prio = []
 		best_prio = 65535
 		sum_weight = 0

src/common/xmpp/transports_nb.py

@@ -298,7 +298,7 @@ class NonBlockingTcp(PlugIn, IdleObject):
 			self.renew_send_timeout()
 		
 	def connect(self,server=None, proxy = None, secure = None):
-		''' Try to establish connection. Returns non-empty string on success. '''
+		''' Try to establish connection. Returns True/False on success/failure. '''
 		if not server:
 			server=self._server
 		else: 
@@ -418,6 +418,12 @@ class NonBlockingTcp(PlugIn, IdleObject):
 			self.idlequeue.remove_timeout(self.fd)
 	
 	def onreceive(self, recv_handler):
+		''' Sets the on_receive callback. Do not confuse it with
+		on_receive() method, which is the callback itself.
+		
+		If recv_handler==None, it tries to set that callback assuming that
+		our owner also has a Dispatcher object plugged in, to its
+		ProcessNonBlocking method.'''
 		if not recv_handler:
 			if hasattr(self._owner, 'Dispatcher'):
 				self.on_receive = self._owner.Dispatcher.ProcessNonBlocking