add comments explaining getattr-related functions and methods

src/core/types.h

@@ -453,6 +453,8 @@ public:
         this->setattr(attr, val, NULL);
     }
 
+    // getattr() does the equivalent of PyDict_GetItem(obj->dict, attr): it looks up the attribute's value on the
+    // object's attribute storage. it doesn't look at other objects or do any descriptor logic.
     Box* getattr(const std::string& attr, GetattrRewriteArgs* rewrite_args);
     Box* getattr(const std::string& attr) { return getattr(attr, NULL); }
     bool hasattr(const std::string& attr) { return getattr(attr) != NULL; }

src/runtime/objmodel.h

@@ -124,10 +124,19 @@ extern "C" void delattr_internal(Box* obj, const std::string& attr, bool allow_c
                                  DelattrRewriteArgs* rewrite_args);
 struct CompareRewriteArgs;
 Box* compareInternal(Box* lhs, Box* rhs, int op_type, CompareRewriteArgs* rewrite_args);
+
+// This is the equivalent of PyObject_GetAttr. Unlike getattrInternalGeneric, it checks for custom __getattr__ or
+// __getattribute__ methods.
 Box* getattrInternal(Box* obj, const std::string& attr, GetattrRewriteArgs* rewrite_args);
+
+// This is the equivalent of PyObject_GenericGetAttr, which performs the default lookup rules for getattr() (check for
+// data descriptor, check for instance attribute, check for non-data descriptor). It does not check for __getattr__ or
+// __getattribute__.
 Box* getattrInternalGeneric(Box* obj, const std::string& attr, GetattrRewriteArgs* rewrite_args, bool cls_only,
                             bool for_call, Box** bind_obj_out, RewriterVar** r_bind_obj_out);
 
+// This is the equivalent of _PyType_Lookup(), which calls Box::getattr() on each item in the object's MRO in the
+// appropriate order. It does not do any descriptor logic.
 Box* typeLookup(BoxedClass* cls, const std::string& attr, GetattrRewriteArgs* rewrite_args);
 
 extern "C" void raiseAttributeErrorStr(const char* typeName, const char* attr) __attribute__((__noreturn__));