From 6b5e9ea7ce9746da792cca0d90d7de5279fcfb08 Mon Sep 17 00:00:00 2001
From: Stephan Erb <steve-e@h3c.de>
Date: Wed, 24 Dec 2008 13:25:57 +0000
Subject: [PATCH] Documentation improvements in client.py

---
 src/common/xmpp/client.py | 47 ++++++++++++++++++++++++++-------------
 1 file changed, 31 insertions(+), 16 deletions(-)

diff --git a/src/common/xmpp/client.py b/src/common/xmpp/client.py
index 8befaec0d..86e78049e 100644
--- a/src/common/xmpp/client.py
+++ b/src/common/xmpp/client.py
@@ -16,23 +16,30 @@
 
 '''
 Provides PlugIn class functionality to develop extentions for xmpppy.
-Also provides Client and Component classes implementations as the
-examples of xmpppy structures usage.
-These classes can be used for simple applications "AS IS" though.
 '''
 
 import logging
 log = logging.getLogger('gajim.c.x.plugin')
 
 class PlugIn:
-	''' Common xmpppy plugins infrastructure: plugging in/out, debugging. '''
+	'''
+	Abstract xmpppy plugin infrastructure code, providing plugging in/out and 
+	debugging functionality.
+
+	Inherit to develop pluggable objects. No code change on the owner class
+	required (the object where we plug into)
+	'''
 	def __init__(self):
 		self._exported_methods=[]
 
-	def PlugIn(self,owner):
-		''' Attach to main instance and register ourself and all our staff in it. '''
+	def PlugIn(self, owner):
+		'''
+		Attach to owner and register ourself and our _exported_methods in it.
+		If defined by a subclass, call self.plugin(owner) to execute hook 
+		code after plugging.
+		'''
 		self._owner=owner
-		log.info('Plugging %s __INTO__ %s' % (self,self._owner))
+		log.info('Plugging %s __INTO__ %s' % (self, self._owner))
 		if self.__class__.__name__ in owner.__dict__:
 			log.debug('Plugging ignored: another instance already plugged.')
 			return
@@ -47,22 +54,30 @@ class PlugIn:
 			owner.__dict__['Dispatcher']=self
 		else:
 			owner.__dict__[self.__class__.__name__]=self
-
-		# following commented line will not work for classes inheriting plugin()
-		#if self.__class__.__dict__.has_key('plugin'): return self.plugin(owner)
-		if hasattr(self,'plugin'): return self.plugin(owner)
+		
+		# Execute hook
+		if hasattr(self,'plugin'):
+			return self.plugin(owner)
 
 	def PlugOut(self):
-		''' Unregister all our staff from main instance and detach from it. '''
+		'''
+		Unregister our _exported_methods from owner and detach from it.
+		If defined by a subclass, call self.plugout() after unplugging to execute
+		hook code.
+		'''
 		log.info('Plugging %s __OUT__ of %s.' % (self, self._owner))
-		for method in self._exported_methods: del self._owner.__dict__[method.__name__]
-		for method in self._old_owners_methods: self._owner.__dict__[method.__name__]=method
+		for method in self._exported_methods:
+			del self._owner.__dict__[method.__name__]
+		for method in self._old_owners_methods:
+			self._owner.__dict__[method.__name__]=method
+		# FIXME: Dispatcher workaround
 		if self.__class__.__name__.endswith('Dispatcher'):
 			del self._owner.__dict__['Dispatcher']
 		else:
 			del self._owner.__dict__[self.__class__.__name__]
-		#if self.__class__.__dict__.has_key('plugout'): return self.plugout()
-		if hasattr(self,'plugout'): return self.plugout()
+		# Execute hook
+		if hasattr(self,'plugout'):
+			return self.plugout()
 		del self._owner
 
 # vim: se ts=3: