Add explanatory comments for submodules

wagtail/core/models/__init__.py

@@ -1,3 +1,14 @@
+"""
+wagtail.core.models is split into submodules for maintainability. All definitions intended as
+public should be imported here (with 'noqa' comments as required) and outside code should continue
+to import them from wagtail.core.models (e.g. `from wagtail.core.models import Site`, not
+`from wagtail.core.models.sites import Site`.)
+
+Submodules should take care to keep the direction of dependencies consistent; where possible they
+should implement low-level generic functionality which is then imported by higher-level models such
+as Page.
+"""
+
 import functools
 import json
 import logging

wagtail/core/models/audit_log.py

@@ -1,3 +1,9 @@
+"""
+Base model definitions for audit logging. These may be subclassed to accommodate specific models
+such as Page, but the definitions here should remain generic and not depend on the base
+wagtail.core.models module or specific models such as Page.
+"""
+
 import json
 
 from django.conf import settings

wagtail/core/models/view_restrictions.py

@@ -1,3 +1,10 @@
+"""
+Base model definitions for validating front-end user access to resources such as pages and
+documents. These may be subclassed to accommodate specific models such as Page or Collection,
+but the definitions here should remain generic and not depend on the base wagtail.core.models
+module or specific models defined there.
+"""
+
 from django.conf import settings
 from django.contrib.auth.models import Group
 from django.db import models