[abac] Rewrite/remove cryptic comments

acs/abac/models.py

@@ -178,17 +178,6 @@ class AssertionAny(models.Model):
         return None
 
 
-'''
-    Multiple assertion definition could be defined for each source
-    However, when it is expected to obtain a thing from any source of
-    a set, it would complexify a lot the rule
-    Then, we allow multiple source for a same assertion.
-
-    An AssertionData has no source, for instance for a comparison,
-    or a unique source
-'''
-
-
 class AssertionDefinition(AssertionAny):
     attribute_definition = models.ForeignKey(AttributeDefinition)
 
@@ -210,6 +199,11 @@ class AttachedSource(models.Model):
 
 
 class AssertionData(AssertionAny):
+    '''
+        An assertion data may have no source or a unique source attached.
+        No source when used in a rule for a comparison for instance.
+        A unique source when used in a profile for instance.
+    '''
     profile = models.ForeignKey(UserAttributeProfile, null=True, blank=True)
     attribute_data = models.ForeignKey(AttributeData)
     source = models.ForeignKey(Source, null=True, blank=True)
@@ -251,12 +245,19 @@ class AssertionData(AssertionAny):
             s += ' (added to profile %s)' % str(self.profile)
         return s
 
-'''
-     We use it to have id of any predicate unique to serve as a
-     variable identifier in the boolean expression
 
-    Maybe we should define a special predicate to require a level of assurance
-    on the authentification for each source
+'''
+    An ABAC rule is a string containing logical statements (and, or, not) and
+    the identifiers of predicates.
+
+    To make feasible to use the the model instance identifiers of predicates,
+    all predicates objects have a unique identifiers with a model defined per
+    predicate type, a parent model is used: Predicate.
+
+    All predicate types (e.g. PredicateRequired) herit from Predicate.
+
+    The identifiers used are thus the identifiers of the instances of the
+    model Predicate
 '''