Added an explanation for how with_metaclass works

1 files changed, 9 insertions, 0 deletions

diff --git a/jinja2/_compat.py b/jinja2/_compat.py
index 5d4fba5..2a0e6ed 100644
--- a/jinja2/_compat.py
+++ b/jinja2/_compat.py
@@ -82,6 +82,15 @@ except NameError:
 
 
 def with_metaclass(meta, *bases):
+    # This requires a bit of explanation: the basic idea is to make a
+    # dummy metaclass for one level of class instanciation that replaces
+    # itself with the actual metaclass.  Because of internal type checks
+    # we also need to make sure that we downgrade the custom metaclass
+    # for one level to something closer to type (that's why __call__ and
+    # __init__ comes back from type etc.).
+    #
+    # This has the advantage over six.with_metaclass in that it does not
+    # introduce dummy classes into the final MRO.
     class __metaclass__(meta):
         __call__ = type.__call__
         __init__ = type.__init__