Document PyTypeObject functions

Author: dean0x7d

include/pybind11/class_support.h

@@ -143,6 +143,8 @@ inline PyTypeObject* make_default_metaclass() {
     return type;
 }
 
+/// Instance creation function for all pybind11 types. It only allocates space for the
+/// C++ object, but doesn't call the constructor -- an `__init__` function must do that.
 extern "C" inline PyObject *pybind11_new(PyTypeObject *type, PyObject *, PyObject *) {
     PyObject *self = type->tp_alloc(type, 0);
     auto instance = (instance_essentials<void> *) self;
@@ -154,6 +156,9 @@ extern "C" inline PyObject *pybind11_new(PyTypeObject *type, PyObject *, PyObjec
     return self;
 }
 
+/// An `__init__` function constructs the C++ object. Users should provide at least one
+/// of these using `py::init` or directly with `.def(__init__, ...)`. Otherwise, the
+/// following default function will be used which simply throws an exception.
 extern "C" inline int pybind11_init(PyObject *self, PyObject *, PyObject *) {
     PyTypeObject *type = Py_TYPE(self);
     std::string msg;
@@ -166,6 +171,8 @@ extern "C" inline int pybind11_init(PyObject *self, PyObject *, PyObject *) {
     return -1;
 }
 
+/// Instance destructor function for all pybind11 types. It calls `type_info.dealloc`
+/// to destroy the C++ object itself, while the rest is Python bookkeeping.
 extern "C" inline void pybind11_dealloc(PyObject *self) {
     auto instance = (instance_essentials<void> *) self;
     if (instance->value) {
@@ -251,6 +258,7 @@ inline PyObject *internals::get_base(size_t instance_size) {
     }
 }
 
+/// dynamic_attr: Support for `d = instance.__dict__`.
 extern "C" inline PyObject *pybind11_get_dict(PyObject *self, void *) {
     PyObject *&dict = *_PyObject_GetDictPtr(self);
     if (!dict)
@@ -259,6 +267,7 @@ extern "C" inline PyObject *pybind11_get_dict(PyObject *self, void *) {
     return dict;
 }
 
+/// dynamic_attr: Support for `instance.__dict__ = dict()`.
 extern "C" inline int pybind11_set_dict(PyObject *self, PyObject *new_dict, void *) {
     if (!PyDict_Check(new_dict)) {
         PyErr_Format(PyExc_TypeError, "__dict__ must be set to a dictionary, not a '%.200s'",
@@ -272,23 +281,42 @@ extern "C" inline int pybind11_set_dict(PyObject *self, PyObject *new_dict, void
     return 0;
 }
 
-static PyGetSetDef pybind11_getset[] = {
-    {const_cast<char*>("__dict__"), pybind11_get_dict, pybind11_set_dict, nullptr, nullptr},
-    {nullptr, nullptr, nullptr, nullptr, nullptr}
-};
-
+/// dynamic_attr: Allow the garbage collector to traverse the internal instance `__dict__`.
 extern "C" inline int pybind11_traverse(PyObject *self, visitproc visit, void *arg) {
     PyObject *&dict = *_PyObject_GetDictPtr(self);
     Py_VISIT(dict);
     return 0;
 }
 
+/// dynamic_attr: Allow the GC to clear the dictionary.
 extern "C" inline int pybind11_clear(PyObject *self) {
     PyObject *&dict = *_PyObject_GetDictPtr(self);
     Py_CLEAR(dict);
     return 0;
 }
 
+/// Give instances of this type a `__dict__` and opt into garbage collection.
+inline void enable_dynamic_attributes(PyHeapTypeObject *heap_type) {
+    auto type = &heap_type->ht_type;
+#if defined(PYPY_VERSION)
+    pybind11_fail(std::string(type->tp_name) + ": dynamic attributes are "
+                                               "currently not supported in "
+                                               "conjunction with PyPy!");
+#endif
+    type->tp_flags |= Py_TPFLAGS_HAVE_GC;
+    type->tp_dictoffset = type->tp_basicsize; // place dict at the end
+    type->tp_basicsize += sizeof(PyObject *); // and allocate enough space for it
+    type->tp_traverse = pybind11_traverse;
+    type->tp_clear = pybind11_clear;
+
+    static PyGetSetDef getset[] = {
+        {const_cast<char*>("__dict__"), pybind11_get_dict, pybind11_set_dict, nullptr, nullptr},
+        {nullptr, nullptr, nullptr, nullptr, nullptr}
+    };
+    type->tp_getset = getset;
+}
+
+/// buffer_protocol: Fill in the view as specified by flags.
 extern "C" inline int pybind11_getbuffer(PyObject *obj, Py_buffer *view, int flags) {
     auto tinfo = get_type_info(Py_TYPE(obj));
     if (view == nullptr || obj == nullptr || !tinfo || !tinfo->get_buffer) {
@@ -318,10 +346,22 @@ extern "C" inline int pybind11_getbuffer(PyObject *obj, Py_buffer *view, int fla
     return 0;
 }
 
+/// buffer_protocol: Release the resources of the buffer.
 extern "C" inline void pybind11_releasebuffer(PyObject *, Py_buffer *view) {
     delete (buffer_info *) view->internal;
 }
 
+/// Give this type a buffer interface.
+inline void enable_buffer_protocol(PyHeapTypeObject *heap_type) {
+    heap_type->ht_type.tp_as_buffer = &heap_type->as_buffer;
+#if PY_MAJOR_VERSION < 3
+    heap_type->ht_type.tp_flags |= Py_TPFLAGS_HAVE_NEWBUFFER;
+#endif
+
+    heap_type->as_buffer.bf_getbuffer = pybind11_getbuffer;
+    heap_type->as_buffer.bf_releasebuffer = pybind11_releasebuffer;
+}
+
 /** Create a brand new Python type according to the `type_record` specification.
     Return value: New reference. */
 inline PyObject* make_new_python_type(const type_record &rec) {
@@ -399,29 +439,11 @@ inline PyObject* make_new_python_type(const type_record &rec) {
     type->tp_flags |= Py_TPFLAGS_CHECKTYPES;
 #endif
 
-    /* Support dynamic attributes */
-    if (rec.dynamic_attr) {
-#if defined(PYPY_VERSION)
-        pybind11_fail(std::string(rec.name) + ": dynamic attributes are "
-                                              "currently not supported in "
-                                              "conjunction with PyPy!");
-#endif
-        type->tp_dictoffset = type->tp_basicsize; // place dict at the end
-        type->tp_basicsize += sizeof(PyObject *); // and allocate enough space for it
-        type->tp_getset = pybind11_getset;
-        type->tp_traverse = pybind11_traverse;
-        type->tp_clear = pybind11_clear;
-        type->tp_flags |= Py_TPFLAGS_HAVE_GC;
-    }
+    if (rec.dynamic_attr)
+        enable_dynamic_attributes(heap_type);
 
-    if (rec.buffer_protocol) {
-        type->tp_as_buffer = &heap_type->as_buffer;
-#if PY_MAJOR_VERSION < 3
-        type->tp_flags |= Py_TPFLAGS_HAVE_NEWBUFFER;
-#endif
-        heap_type->as_buffer.bf_getbuffer = pybind11_getbuffer;
-        heap_type->as_buffer.bf_releasebuffer = pybind11_releasebuffer;
-    }
+    if (rec.buffer_protocol)
+        enable_buffer_protocol(heap_type);
 
     if (PyType_Ready(type) < 0)
         pybind11_fail(std::string(rec.name) + ": PyType_Ready failed (" + error_string() + ")!");