threading: improve comments

Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>

offlineimap/folder/Base.py

@@ -1,5 +1,5 @@
 # Base folder support
-# Copyright (C) 2002-2015 John Goerzen & contributors
+# Copyright (C) 2002-2016 John Goerzen & contributors
 #
 #    This program is free software; you can redistribute it and/or modify
 #    it under the terms of the GNU General Public License as published by
@@ -832,7 +832,7 @@ class BaseFolder(object):
         except Exception as e:
             self.ui.error(e, exc_info()[2],
               msg = "Copying message %s [acc: %s]"% (uid, self.accountname))
-            raise    #raise on unknown errors, so we can fix those
+            raise  # Raise on unknown errors, so we can fix those.
 
     def __syncmessagesto_copy(self, dstfolder, statusfolder):
         """Pass1: Copy locally existing messages not on the other side.
@@ -870,7 +870,8 @@ class BaseFolder(object):
                 continue
 
             self.ui.copyingmessage(uid, num+1, num_to_copy, self, dstfolder)
-            # exceptions are caught in copymessageto()
+
+            # Exceptions are caught in copymessageto().
             if self.suggeststhreads():
                 self.waitforthread()
                 thread = threadutil.InstanceLimitedThread(
@@ -884,7 +885,7 @@ class BaseFolder(object):
             else:
                 self.copymessageto(uid, dstfolder, statusfolder, register=0)
         for thread in threads:
-            thread.join()
+            thread.join() # Block until all "copy" threads are done.
 
         # Execute new mail hook if we have new mail.
         if self.have_newmail:

offlineimap/imapserver.py

@@ -621,7 +621,7 @@ class IMAPServer(object):
         It's OK if we have maxconnections + 1 or 2 threads, which is what this
         will help us do."""
 
-        self.semaphore.acquire()
+        self.semaphore.acquire() # Blocking until maxconnections has free slots.
         self.semaphore.release()
 
     def close(self):

offlineimap/threadutil.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2002-2012 John Goerzen & contributors
+# Copyright (C) 2002-2016 John Goerzen & contributors
 # Thread support module
 #
 #    This program is free software; you can redistribute it and/or modify
@@ -243,6 +243,7 @@ class InstanceLimitedThread(ExitNotifyThread):
     def start(self):
         global limitedNamespaces
 
+        # Will block until the semaphore has free slots.
         limitedNamespaces[self.limitNamespace].acquire()
         ExitNotifyThread.start(self)