Beefed up the comments for AppConfig.all_models.

django/apps/base.py

@@ -96,9 +96,10 @@ class AppConfig(object):
             return cls(entry)
 
     def import_models(self, all_models):
-        # Dictionary of models for this app, stored in the 'all_models'
-        # attribute of the Apps this AppConfig is attached to. Injected as a
-        # parameter because it may get populated before this method has run.
+        # Dictionary of models for this app, primarily maintained in the
+        # 'all_models' attribute of the Apps this AppConfig is attached to.
+        # Injected as a parameter because it gets populated when models are
+        # imported, which may happen before populate_models() runs.
         self.models = all_models
 
         if module_has_submodule(self.app_module, MODELS_MODULE_NAME):

django/apps/registry.py

@@ -32,9 +32,13 @@ class Apps(object):
         # get_model[s].
         self.master = master
 
-        # Mapping of app labels => model names => model classes. Used to
-        # register models before the registry is populated and also for
-        # applications that aren't installed.
+        # Mapping of app labels => model names => model classes. Every time a
+        # model is imported, ModelBase.__new__ calls apps.register_model which
+        # creates an entry in all_models. All imported models are registered,
+        # regardless of whether they're defined in an installed application
+        # and whether the registry has been populated. Since it isn't possible
+        # to reimport a module safely (it could reexecute initialization code)
+        # all_models is never overridden or reset.
         self.all_models = defaultdict(OrderedDict)
 
         # Mapping of labels to AppConfig instances for installed apps.