Added an explanation for how with_metaclass works

diff --git a/jinja2/_compat.py b/jinja2/_compat.py
index 5d4fba54bafca76fbcc805eaf5a1d2eba7165b12..2a0e6ed876a4ca7655aba06e64bee102e51404ff 100644 (file)
--- 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__