From 3b04d88441ee44fe557f7baff4ba408e55ad19cf Mon Sep 17 00:00:00 2001
From: Jan-Jelle Kester <janjelle@jjkester.nl>
Date: Fri, 15 May 2015 01:25:44 +0200
Subject: [PATCH] Improve code documentation

---
 src/auditlog/diff.py     | 11 +++++++++--
 src/auditlog/models.py   | 11 ++++++++++-
 src/auditlog/registry.py | 23 +++++++++++++++++------
 3 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/src/auditlog/diff.py b/src/auditlog/diff.py
index b8194e2..644ace8 100644
--- a/src/auditlog/diff.py
+++ b/src/auditlog/diff.py
@@ -5,11 +5,18 @@ from django.db.models import Model
 from django.utils.encoding import smart_text
 
 
-def model_instance_diff(old, new, **kwargs):
+def model_instance_diff(old, new):
     """
-    Calculate the differences between two model instances. One of the instances may be None (i.e., a newly
+    Calculates the differences between two model instances. One of the instances may be None (i.e., a newly
     created model or deleted model). This will cause all fields with a value to have changed (from None).
 
+    :param old: The old state of the model instance.
+    :type old: Model
+    :param new: The new state of the model instance.
+    :type new: Model
+    :return: A dictionary with the names of the changed fields as keys and a two tuple of the old and new field values
+             as value.
+    :rtype: {str: (str|None, str|None)}
     """
     from auditlog.registry import auditlog
 
diff --git a/src/auditlog/models.py b/src/auditlog/models.py
index ad0184b..1112393 100644
--- a/src/auditlog/models.py
+++ b/src/auditlog/models.py
@@ -144,7 +144,7 @@ class LogEntry(models.Model):
     @property
     def changes_dict(self):
         """
-        Return the changes recorded in this log entry as a dictionary object.
+        :return: The changes recorded in this log entry as a dictionary object.
         """
         try:
             return json.loads(self.changes)
@@ -157,6 +157,11 @@ class LogEntry(models.Model):
         Return the changes recorded in this log entry as a string. The formatting of the string can be customized by
         setting alternate values for colon, arrow and separator. If the formatting is still not satisfying, please use
         changes_dict() and format the string yourself.
+
+        :param colon: The string to place between the field name and the values.
+        :param arrow: The string to place between each old and new value.
+        :param separator: The string to place between each field.
+        :return: A readable string of the changes in this log entry.
         """
         substrings = []
 
@@ -187,6 +192,10 @@ class AuditlogHistoryField(generic.GenericRelation):
     """
 
     def __init__(self, pk_indexable=True, **kwargs):
+        """
+        :param pk_indexable: Whether the primary key for this model is not an integer or long.
+        :type pk_indexable: bool
+        """
         kwargs['to'] = LogEntry
 
         if pk_indexable:
diff --git a/src/auditlog/registry.py b/src/auditlog/registry.py
index 0a530bd..c5a8a4d 100644
--- a/src/auditlog/registry.py
+++ b/src/auditlog/registry.py
@@ -24,18 +24,21 @@ class AuditlogModelRegistry(object):
         if custom is not None:
             self._signals.update(custom)
 
-    def register(self, model, **kwargs):
+    def register(self, model, include_fields=[], exclude_fields=[]):
         """
         Register a model with auditlog. Auditlog will then track mutations on this model's instances.
 
-        Kwargs:
-          - `include_fields`: list of field names to include in diff
-          - `exclude_fields`: list of field names to exclude in diff
+        :param model: The model to register.
+        :type model: Model
+        :param include_fields: The fields to include. Implicitly excludes all other fields.
+        :type include_fields: [str]
+        :param exclude_fields: The fields to exclude. Overrides the fields to include.
+        :type exclude_fields: [str]
         """
         if issubclass(model, Model):
             self._registry[model] = {
-                'include_fields': kwargs.get('include_fields', []),
-                'exclude_fields': kwargs.get('exclude_fields', []),
+                'include_fields': include_fields,
+                'exclude_fields': exclude_fields,
             }
             self._connect_signals(model)
         else:
@@ -44,12 +47,20 @@ class AuditlogModelRegistry(object):
     def contains(self, model):
         """
         Check if a model is registered with auditlog.
+
+        :param model: The model to check.
+        :type model: Model
+        :return: Whether the model has been registered.
+        :rtype: bool
         """
         return model in self._registry
 
     def unregister(self, model):
         """
         Unregister a model with auditlog. This will not affect the database.
+
+        :param model: The model to unregister.
+        :type model: Model
         """
         try:
             del self._registry[model]