From 1b2503d371c4c3a1278c99d7862db3084baf1f5f Mon Sep 17 00:00:00 2001
From: Jan-Jelle Kester <janjelle@jjkester.nl>
Date: Wed, 6 Nov 2013 20:48:16 +0100
Subject: [PATCH] Extend inline documentation

---
 src/auditlog/middleware.py | 13 +++++++++++++
 src/auditlog/models.py     |  4 ++--
 src/auditlog/registry.py   |  2 +-
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/src/auditlog/middleware.py b/src/auditlog/middleware.py
index 6d729e6..a690694 100644
--- a/src/auditlog/middleware.py
+++ b/src/auditlog/middleware.py
@@ -11,6 +11,10 @@ class AuditLogMiddleware(object):
     """
 
     def process_request(self, request):
+        """
+        Gets the current user from the request and prepares and connects a signal receiver with the user already
+        attached to it.
+        """
         if hasattr(request, 'user') and hasattr(request.user, 'is_authenticated') and request.user.is_authenticated():
             user = request.user
         else:
@@ -20,9 +24,18 @@ class AuditLogMiddleware(object):
         pre_save.connect(set_actor, sender=LogEntry, dispatch_uid=(self.__class__, request), weak=False)
 
     def process_response(self, request, response):
+        """
+        Disconnects the signal receiver to prevent it from staying active.
+        """
+        # Disconnecting the signal receiver is required because it will not be garbage collected (non-weak reference)
         pre_save.disconnect(dispatch_uid=(self.__class__, request))
+
         return response
 
     def set_actor(self, user, sender, instance, **kwargs):
+        """
+        Signal receiver with an extra, required 'user' kwarg. This method becomes a real (valid) signal receiver when
+        it is curried with the actor.
+        """
         if sender == LogEntry and isinstance(user, settings.AUTH_USER_MODEL) and instance.actor is None:
             instance.actor = user
diff --git a/src/auditlog/models.py b/src/auditlog/models.py
index 94329ff..41a614e 100644
--- a/src/auditlog/models.py
+++ b/src/auditlog/models.py
@@ -30,8 +30,8 @@ class LogEntryManager(models.Manager):
                 if isinstance(pk, int):
                     kwargs['object_id'] = pk
 
-            # Delete log entries with the same pk as a newly created model. This should only happen when all records were
-            # deleted / the table was truncated.
+            # Delete log entries with the same pk as a newly created model. This should only be necessary when an pk is
+            # used twice.
             if kwargs.get('action', None) is LogEntry.Action.CREATE:
                 if kwargs.get('object_id', None) is not None and self.filter(content_type=kwargs.get('content_type'), object_id=kwargs.get('object_id')).exists():
                     self.filter(content_type=kwargs.get('content_type'), object_id=kwargs.get('object_id')).delete()
diff --git a/src/auditlog/registry.py b/src/auditlog/registry.py
index dace2eb..ff078ca 100644
--- a/src/auditlog/registry.py
+++ b/src/auditlog/registry.py
@@ -5,7 +5,7 @@ from auditlog.receivers import log_create, log_update, log_delete
 
 class AuditLogModelRegistry(object):
     """
-    A registry that keeps track of the models that use auditlog.
+    A registry that keeps track of the models that use Auditlog to track changes.
     """
 
     def __init__(self, create=True, update=True, delete=True, custom=None):