Adding source code comments in response to review.

include/pybind11/cast.h

@@ -11,9 +11,16 @@
 
 #pragma once
 
+// clang-format on
 #ifndef PYBIND11_USE_SMART_HOLDER_AS_DEFAULT
 // #define PYBIND11_USE_SMART_HOLDER_AS_DEFAULT
+// Currently the main purpose of this switch is to enable non-intrusive comprehensive testing. If
+// and when `smart_holder` will actually become the released default is currently open. In the
+// meantime, the full functionality is easily available by using `py::classh`, which is just a
+// handy shortcut for `py::class_<T, py::smart_holder>` (see `pybind11/smart_holder.h`). Classes
+// wrapped in this way are fully compatible with everything existing.
 #endif
+// clang-format off
 
 #include "pytypes.h"
 #include "detail/typeid.h"

include/pybind11/detail/smart_holder_poc.h

@@ -154,6 +154,7 @@ struct smart_holder {
         // race conditions, but in the context of Python it is a bug (elsewhere)
         // if the Global Interpreter Lock (GIL) is not being held when this code
         // is reached.
+        // SMART_HOLDER_WIP: IMPROVABLE: assert(GIL is held).
         if (vptr.use_count() != 1) {
             throw std::runtime_error(std::string("Cannot disown use_count != 1 (") + context
                                      + ").");

include/pybind11/detail/smart_holder_type_casters_inline_include.h

@@ -229,6 +229,8 @@ public:
     bool reinterpret_cast_deemed_ok = false;
     // Magic number intentionally hard-coded, to guard against class_ holder mixups.
     // Ideally type_caster_generic would have a similar guard, but this requires a change there.
+    // SMART_HOLDER_WIP: If it is decided that this guard is useful long term, potentially
+    // set/reset this value in ctor/dtor, mark volatile.
     std::size_t local_load_safety_guard = 1887406645; // 32-bit compatible value for portability.
 };
 // clang-format on