Add more comments

python/gtsam/preamble.h

@@ -1,5 +1,13 @@
-// Please refer to: https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html
+/* Please refer to: https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html
-// These are required to save one copy operation on Python calls
+ * 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

python/gtsam/specializations.h

@@ -1,5 +1,17 @@
-// Please refer to: https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html
+/* Please refer to: https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html
-// These are required to save one copy operation on Python calls
+ * 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> > >();