Wrote down the invariants of some common objects whose structure is
exposed in header files.  Fixed a few comments in these headers.

As we might have expected, writing down invariants systematically exposed a
(minor) bug.  In this case, function objects have a writeable func_code
attribute, which could be set to code objects with the wrong number of
free variables.  Calling the resulting function segfaulted the interpreter.
Added a corresponding test.
diff --git a/Lib/test/test_funcattrs.py b/Lib/test/test_funcattrs.py
index 381412f..1acfeb5 100644
--- a/Lib/test/test_funcattrs.py
+++ b/Lib/test/test_funcattrs.py
@@ -218,11 +218,11 @@
 
 # Test all predefined function attributes systematically
 
-def cantset(obj, name, value):
+def cantset(obj, name, value, exception=(AttributeError, TypeError)):
     verify(hasattr(obj, name)) # Otherwise it's probably a typo
     try:
         setattr(obj, name, value)
-    except (AttributeError, TypeError):
+    except exception:
         pass
     else:
         raise TestFailed, "shouldn't be able to set %s to %r" % (name, value)
@@ -279,11 +279,20 @@
 
 
 def test_func_code():
+    a = b = 24
     def f(): pass
     def g(): print 12
+    def f1(): print a
+    def g1(): print b
+    def f2(): print a, b
     verify(type(f.func_code) is types.CodeType)
     f.func_code = g.func_code
     cantset(f, "func_code", None)
+    # can't change the number of free vars
+    cantset(f,  "func_code", f1.func_code, exception=ValueError)
+    cantset(f1, "func_code",  f.func_code, exception=ValueError)
+    cantset(f1, "func_code", f2.func_code, exception=ValueError)
+    f1.func_code = g1.func_code
 
 def test_func_defaults():
     def f(a, b): return (a, b)