Add some comments to the code.

src/capi/typeobject.h

@@ -19,6 +19,14 @@
 
 namespace pyston {
 
+/*
+ * Type objects refer to Python's new-style classes that inherit from
+ * `object`. This, classes declared as:
+ *
+ * class Foo(object):
+ *  ...
+ */
+
 // Returns if a slot was updated
 bool update_slot(BoxedClass* self, llvm::StringRef attr) noexcept;
 

src/codegen/ast_interpreter.cpp

@@ -75,6 +75,12 @@ public:
     static void deregister(void* frame_addr);
 };
 
+/*
+ * ASTInterpreters exist per function frame - there's no global interpreter object that executes
+ * all non-jitted code!
+ *
+ * The ASTInterpreter inherits from Box as part of garbage collection support.
+ */
 class ASTInterpreter : public Box {
 public:
     typedef ContiguousMap<InternedString, Box*> SymMap;

src/core/types.h

@@ -481,6 +481,12 @@ public:
 class BoxedDict;
 class BoxedString;
 
+// In Pyston, this is the same type as CPython's PyObject (they are interchangeable, but we
+// use Box in Pyston wherever possible as a convention).
+//
+// Other types on Pyston inherit from Box (e.g. BoxedString is a Box). Why is this class not
+// polymorphic? Because of C extension support -- having virtual methods would change the layout
+// of the object.
 class Box {
 private:
     BoxedDict** getDictPtr();

src/runtime/classobj.h

@@ -19,6 +19,17 @@
 
 namespace pyston {
 
+/*
+ * Class objects refer to Python's old-style classes that don't inherit from
+ * `object`. This, classes declared as:
+ *
+ * class Foo:
+ *  ...
+ *
+ * When debugging, "obj->cls->tp_name" will have value "instance" for all
+ * old-style classes rather than the name of the class itself.
+ */
+
 void setupClassobj();
 
 class BoxedClass;

src/runtime/types.h

@@ -142,7 +142,8 @@ extern "C" void printFloat(double d);
 Box* objectStr(Box*);
 Box* objectRepr(Box*);
 
-
+// In Pyston, this is the same type as CPython's PyTypeObject (they are interchangeable, but we
+// use BoxedClass in Pyston wherever possible as a convention).
 class BoxedClass : public BoxVar {
 public:
     typedef void (*gcvisit_func)(GCVisitor*, Box*);