Beefed up the comments for AppConfig.all_models.

2 files changed, 11 insertions, 6 deletions

diff --git a/django/apps/base.py b/django/apps/base.py
index f1baaa5adf..5d2cfd88a7 100644
--- a/django/apps/base.py
+++ b/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):
diff --git a/django/apps/registry.py b/django/apps/registry.py
index bedd8cdb02..2a09513152 100644
--- a/django/apps/registry.py
+++ b/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.