py/obj: Clean up and add comments describing mp_obj_type_t struct.

dpgeorge · dpgeorge · commit fc710169b7fd · 2017-04-12T13:20:26.000+10:00
diff --git a/py/obj.h b/py/obj.h
@@ -470,16 +470,27 @@ typedef struct _mp_stream_p_t {
 } mp_stream_p_t;
 
 struct _mp_obj_type_t {
+    // A type is an object so must start with this entry, which points to mp_type_type.
     mp_obj_base_t base;
+
+    // The name of this type.
     qstr name;
+
+    // Corresponds to __repr__ and __str__ special methods.
     mp_print_fun_t print;
-    mp_make_new_fun_t make_new;     // to make an instance of the type
 
+    // Corresponds to __new__ and __init__ special methods, to make an instance of the type.
+    mp_make_new_fun_t make_new;
+
+    // Corresponds to __call__ special method, ie T(...).
     mp_call_fun_t call;
-    mp_unary_op_fun_t unary_op;     // can return MP_OBJ_NULL if op not supported
-    mp_binary_op_fun_t binary_op;   // can return MP_OBJ_NULL if op not supported
 
-    // implements load, store and delete attribute
+    // Implements unary and binary operations.
+    // Can return MP_OBJ_NULL if the operation is not supported.
+    mp_unary_op_fun_t unary_op;
+    mp_binary_op_fun_t binary_op;
+
+    // Implements load, store and delete attribute.
     //
     // dest[0] = MP_OBJ_NULL means load
     //  return: for fail, do nothing
@@ -492,35 +503,33 @@ struct _mp_obj_type_t {
     //          for success set dest[0] = MP_OBJ_NULL
     mp_attr_fun_t attr;
 
-    mp_subscr_fun_t subscr;         // implements load, store, delete subscripting
-                                    // value=MP_OBJ_NULL means delete, value=MP_OBJ_SENTINEL means load, else store
-                                    // can return MP_OBJ_NULL if op not supported
+    // Implements load, store and delete subscripting:
+    //  - value = MP_OBJ_SENTINEL means load
+    //  - value = MP_OBJ_NULL means delete
+    //  - all other values mean store the value
+    // Can return MP_OBJ_NULL if operation not supported.
+    mp_subscr_fun_t subscr;
 
-    // corresponds to __iter__ special method
-    // can use given mp_obj_iter_buf_t to store iterator
-    // otherwise can return a pointer to an object on the heap
+    // Corresponds to __iter__ special method.
+    // Can use the given mp_obj_iter_buf_t to store iterator object,
+    // otherwise can return a pointer to an object on the heap.
     mp_getiter_fun_t getiter;
 
-    mp_fun_1_t iternext; // may return MP_OBJ_STOP_ITERATION as an optimisation instead of raising StopIteration() (with no args)
+    // Corresponds to __next__ special method.  May return MP_OBJ_STOP_ITERATION
+    // as an optimisation instead of raising StopIteration() with no args.
+    mp_fun_1_t iternext;
 
+    // Implements the buffer protocol if supported by this type.
     mp_buffer_p_t buffer_p;
+
     // One of disjoint protocols (interfaces), like mp_stream_p_t, etc.
     const void *protocol;
 
-    // these are for dynamically created types (classes)
+    // A tuple containing all the base types of this type.
     struct _mp_obj_tuple_t *bases_tuple;
-    struct _mp_obj_dict_t *locals_dict;
-
-    /*
-    What we might need to add here:
 
-    len             str tuple list map
-    abs             float complex
-    hash            bool int none str
-    equal           int str
-
-    unpack seq      list tuple
-    */
+    // A dict mapping qstrs to objects local methods/constants/etc.
+    struct _mp_obj_dict_t *locals_dict;
 };
 
 // Constant types, globally accessible
