Code documentation improvements

src/tixlbase/cache.py

@@ -15,8 +15,9 @@ class EventRelatedCache:
     main purpose of this is to be able to flush all cached data related
     to this event at once.
 
-    The object is stateless, all state is in the cache, so you can
-    instantiate it as many times as you want.
+    The EventRelatedCache instance itself is stateless, all state is
+    stored in the cache backend, so you can instantiate this class as many
+    times as you want.
     """
 
     def __init__(self, event: Event, cache: str='default'):

src/tixlbase/forms.py

@@ -4,6 +4,9 @@ from versions.models import Versionable
 
 
 class VersionedBaseModelForm(BaseModelForm):
+    """
+    This is a helperclass to construct VersionedModelForm
+    """
     def save(self, commit=True):
         if self.instance.pk is not None and isinstance(self.instance, Versionable):
             if self.has_changed():
@@ -12,4 +15,11 @@ class VersionedBaseModelForm(BaseModelForm):
 
 
 class VersionedModelForm(six.with_metaclass(ModelFormMetaclass, VersionedBaseModelForm)):
+    """
+    This is a modified version of Django's ModelForm which differs from ModelForm in
+    only one way: It executes the .clone() method of an object before saving it back to
+    the database, if the model is a sub-class of versions.models.Versionable. You can
+    safely use this as a base class for all your model forms, it will work out correctly
+    with both versioned and non-versioned models.
+    """
     pass

src/tixlbase/models.py

@@ -349,7 +349,8 @@ class EventPermission(Versionable):
 
 class ItemCategory(Versionable):
     """
-    Items can be sorted into categories
+    Items can be sorted into categories, which only have a name and a
+    configurable order
     """
     event = VersionedForeignKey(
         Event,
@@ -385,9 +386,8 @@ class ItemCategory(Versionable):
 
 class Property(Versionable):
     """
-    A property is a modifier which can be applied to an
-    Item. For example 'Size' would be a property associated
-    with the item 'T-Shirt'.
+    A property is a modifier which can be applied to an Item. For example
+    'Size' would be a property associated with the item 'T-Shirt'.
     """
 
     event = VersionedForeignKey(

src/tixlbase/plugins.py

@@ -1,7 +1,7 @@
 try:  # NOQA
     from enum import Enum
 except ImportError:  # NOQA
-    from flufl.enum import Enum
+    from flufl.enum import Enum  # remove this dependency when support for python <=3.3 is dropped
 
 from django.apps import apps
 
@@ -10,7 +10,10 @@ class PluginType(Enum):
     RESTRICTION = 1
 
 
-def get_all_plugins() -> "class":
+def get_all_plugins() -> "List[class]":
+    """
+    Returns the TixlPluginMeta classes of all plugins found in the installed Django apps.
+    """
     plugins = []
     for app in apps.get_app_configs():
         if hasattr(app, 'TixlPluginMeta'):

src/tixlbase/signals.py

@@ -4,6 +4,11 @@ from django.dispatch.dispatcher import NO_RECEIVERS
 
 
 class EventPluginSignal(django.dispatch.Signal):
+    """
+    This is an extension to Django's built-in signals which differs in a way that it sends
+    out it's events only to receivers which belong to plugins that are enabled for the given
+    Event.
+    """
 
     def send(self, sender, **named):
         """
@@ -34,6 +39,11 @@ class EventPluginSignal(django.dispatch.Signal):
                 responses.append((receiver, response))
         return responses
 
+"""
+This signal is sent out every time some component of tixl wants to know whether a specific
+item or variation is available for sell. The item will only be sold, if all (active) receivers
+return a positive result (see plugin API documentation for details).
+"""
 determine_availability = EventPluginSignal(
     providing_args=["item", "variations", "context", "cache"]
 )