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/Objects/funcobject.c b/Objects/funcobject.c
index c46887c..c7f7c9d 100644
--- a/Objects/funcobject.c
+++ b/Objects/funcobject.c
@@ -230,6 +230,7 @@
 func_set_code(PyFunctionObject *op, PyObject *value)
 {
 	PyObject *tmp;
+	int nfree, nclosure;
 
 	if (restricted())
 		return -1;
@@ -240,6 +241,17 @@
 				"func_code must be set to a code object");
 		return -1;
 	}
+	nfree = PyCode_GetNumFree((PyCodeObject *)value);
+	nclosure = (op->func_closure == NULL ? 0 :
+		    PyTuple_GET_SIZE(op->func_closure));
+	if (nclosure != nfree) {
+		PyErr_Format(PyExc_ValueError,
+			     "%s() requires a code object with %d free vars,"
+			     " not %d",
+			     PyString_AsString(op->func_name),
+			     nclosure, nfree);
+		return -1;
+	}
 	tmp = op->func_code;
 	Py_INCREF(value);
 	op->func_code = value;