Ticket #8981: patch.diff

trunk/django/db/models/base.py

@@ -33 +33 @@
             # If this isn't a subclass of Model, don't do anything special.
             return super_new(cls, name, bases, attrs)
 
-        # Create the class.
+        # extract the __module__ value for creating the new class
+        # also used for creating individual subclasses of 
+        # ObjectDoesNotExist, MultipleObjectsReturned
         module = attrs.pop('__module__')
+        # Create the class.        
+        # notice that each attrs is ignored except for __module__
+        # other attrs are added later
         new_class = super_new(cls, name, bases, {'__module__': module})
+        # get reference to enclosed Meta class, and determine if this class was 
+        # decalred as abstract
+        # if there is no Meta class, attr_meta = None
         attr_meta = attrs.pop('Meta', None)
         abstract = getattr(attr_meta, 'abstract', False)
+        # if there isn't a Meta class, try and find one from an ancestor class
         if not attr_meta:
             meta = getattr(new_class, 'Meta', None)
         else:
             meta = attr_meta
+        # meta is now the reference to a Meta class, if any
+        # retrive an inherited _meta, if any
         base_meta = getattr(new_class, '_meta', None)
-
+        
+        # attempt to set the app_label value
         if getattr(meta, 'app_label', None) is None:
             # Figure out the app_label by looking one level up.
             # For 'django.contrib.sites.models', this would be 'sites'.
@@ -51 +63 @@
             kwargs = {"app_label": model_module.__name__.split('.')[-2]}
         else:
             kwargs = {}
-
+        
+        #attach the _meta attribute, an instance of Options
         new_class.add_to_class('_meta', Options(meta, **kwargs))
+        # setup non-abstract classes
         if not abstract:
+          # add error classes as attributes into class we're constructing unless it's abstract
             new_class.add_to_class('DoesNotExist',
                     subclass_exception('DoesNotExist', ObjectDoesNotExist, module))
             new_class.add_to_class('MultipleObjectsReturned',
                     subclass_exception('MultipleObjectsReturned', MultipleObjectsReturned, module))
             if base_meta and not base_meta.abstract:
-                # Non-abstract child classes inherit some attributes from their
+                # Non-abstract child classes inherit some _meta attributes from their
                 # non-abstract parent (unless an ABC comes before it in the
                 # method resolution order).
                 if not hasattr(meta, 'ordering'):
@@ -67 +82 @@
                 if not hasattr(meta, 'get_latest_by'):
                     new_class._meta.get_latest_by = base_meta.get_latest_by
 
+        # determine if there is an inherited default_manager, if not explicity set it to None
         if getattr(new_class, '_default_manager', None):
             new_class._default_manager = None
 
         # Bail out early if we have already created this class.
+        # all models are registered in a Borg pattern class
         m = get_model(new_class._meta.app_label, name, False)
         if m is not None:
             return m
 
         # Add all attributes to the class.
+        # since different attributes need to be added in different ways, they weren't
+        # included in the namespace attribute for the type.__new__() call
+        # add_to_class will either attach them normally (setattr) or use the attribute's 
+        # add_to_class method, if it exists
         for obj_name, obj in attrs.items():
             new_class.add_to_class(obj_name, obj)
 
@@ -94 +115 @@
                          new_class._meta.virtual_fields
             field_names = set([f.name for f in new_fields])
 
+            # for multi-table inheritance, add a one-to-one relation between
+            # the child class (the class curently being constructed) and the parent class
             if not base._meta.abstract:
                 # Concrete classes...
                 if base in o2o_map:
@@ -159 +182 @@
         # registered version.
         return get_model(new_class._meta.app_label, name, False)
 
+    # method for adding attributes to the class being constructed
     def add_to_class(cls, name, value):
         if hasattr(value, 'contribute_to_class'):
             value.contribute_to_class(cls, name)

trunk/django/db/models/options.py

@@ -23 +23 @@
                  'order_with_respect_to', 'app_label', 'db_tablespace',
                  'abstract')
 
+# instance of this class becomes somemodel._meta
+# this class' instances are attached while the model class is being
+# constructued and before the model's __init__() is run
 class Options(object):
     def __init__(self, meta, app_label=None):
         self.local_fields, self.local_many_to_many = [], []
@@ -49 +52 @@
         # are passed onto any children.
         self.abstract_managers = []
 
+    # method for adding instance of Options to a model 
     def contribute_to_class(self, cls, name):
         from django.db import connection
         from django.db.backends.util import truncate_name
 
         cls._meta = self
+        # installed is boolean, details whether this model makes up part of an
+        # installed application
         self.installed = re.sub('\.models$', '', cls.__module__) in settings.INSTALLED_APPS
         # First, construct the default values for these options.
         self.object_name = cls.__name__

trunk/django/db/models/fields/__init__.py

@@ -154 +154 @@
         if self.verbose_name is None and name:
             self.verbose_name = name.replace('_', ' ')
 
+    # method for adding a field to a model class
+    # faily general purposes, only subclassed a couple times
     def contribute_to_class(self, cls, name):
         self.set_attributes_from_name(name)
         cls._meta.add_field(self)