diff --git a/python/gtsam/preamble.h b/python/gtsam/preamble.h
index dd1b342eb..7294a6ac8 100644
--- a/python/gtsam/preamble.h
+++ b/python/gtsam/preamble.h
@@ -1,5 +1,13 @@
-// Please refer to: https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html
-// These are required to save one copy operation on Python calls
+/* Please refer to: https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html
+ * These are required to save one copy operation on Python calls.
+ *
+ * NOTES
+ * =================
+ *
+ * `PYBIND11_MAKE_OPAQUE` will mark the type as "opaque" for the pybind11 automatic STL binding,
+ * such that the raw objects can be accessed in Python. Without this they will be automatically
+ * converted to a Python object, and all mutations on Python side will not be reflected on C++.
+ */
 #ifdef GTSAM_ALLOCATOR_TBB
 PYBIND11_MAKE_OPAQUE(std::vector<gtsam::Key, tbb::tbb_allocator<gtsam::Key>>);
 #else
diff --git a/python/gtsam/specializations.h b/python/gtsam/specializations.h
index c6efd2f71..be8eb8a6c 100644
--- a/python/gtsam/specializations.h
+++ b/python/gtsam/specializations.h
@@ -1,5 +1,17 @@
-// Please refer to: https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html
-// These are required to save one copy operation on Python calls
+/* Please refer to: https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html
+ * These are required to save one copy operation on Python calls.
+ *
+ * NOTES
+ * =================
+ *
+ * `PYBIND11_MAKE_OPAQUE` will mark the type as "opaque" for the pybind11 automatic STL binding,
+ * such that the raw objects can be accessed in Python. Without this they will be automatically
+ * converted to a Python object, and all mutations on Python side will not be reflected on C++.
+ *
+ * `py::bind_vector` and similar machinery gives the std container a Python-like interface, but
+ * without the `<pybind11/stl.h>` copying mechanism. Combined with `PYBIND11_MAKE_OPAQUE` this
+ * allows the types to be modified with Python, and saves one copy operation.
+ */
 #ifdef GTSAM_ALLOCATOR_TBB
 py::bind_vector<std::vector<gtsam::Key, tbb::tbb_allocator<gtsam::Key> > >(m_, "KeyVector");
 py::implicitly_convertible<py::list, std::vector<gtsam::Key, tbb::tbb_allocator<gtsam::Key> > >();