Added a docstring note about the convention for when save_*_in_history() shoudl be called.

 - Legacy-Id: 4883

Author: levkowetz

ietf/doc/models.py

@@ -379,6 +379,12 @@ class Meta:
         verbose_name_plural = "document histories"
 
 def save_document_in_history(doc):
+    """This should be called before saving changes to a Document instance,
+    so that the DocHistory entries contain all previous states, while
+    the Group entry contain the current state.  XXX TODO: Call this
+    directly from Document.save(), and add event listeners for save()
+    on related objects so we can save as needed when they change, too.
+    """
     def get_model_fields_as_dict(obj):
         return dict((field.name, getattr(obj, field.name))
                     for field in obj._meta.fields

ietf/group/utils.py

@@ -6,6 +6,11 @@
 
 
 def save_group_in_history(group):
+    """This should be called before saving changes to a Group instance,
+    so that the GroupHistory entries contain all previous states, while
+    the Group entry contain the current state.  XXX TODO: Call this
+    directly from Group.save()
+    """
     def get_model_fields_as_dict(obj):
         return dict((field.name, getattr(obj, field.name))
                     for field in obj._meta.fields