Update docs/advanced/classes.rst and C++ comments → potentially_slicing_weak_ptr

Author: rwgk

docs/advanced/classes.rst

@@ -459,9 +459,9 @@ inheritance slicing but can lead to unintended behavior when creating
 ``std::weak_ptr`` instances
 (see `#5623 <https://github.com/pybind/pybind11/issues/5623>`_).
 
-If it is necessary to obtain a ``std::shared_ptr`` that shares the control block
+If it is necessary to obtain a ``std::weak_ptr`` that shares the control block
 with the ``smart_holder``—at the cost of reintroducing potential inheritance
-slicing—you can use ``py::potentially_slicing_shared_ptr<T>(obj)``.
+slicing—you can use ``py::potentially_slicing_weak_ptr<T>(obj)``.
 
 When precise lifetime management of derived Python objects is important,
 using a Python-side ``weakref`` is the most reliable approach, as it avoids
@@ -470,8 +470,8 @@ semantics in C++.
 
 .. seealso::
 
-    * :func:`potentially_slicing_shared_ptr` C++ documentation
-    * :file:`tests/test_potentially_slicing_shared_ptr.cpp`
+    * :func:`potentially_slicing_weak_ptr` C++ documentation
+    * :file:`tests/test_potentially_slicing_weak_ptr.cpp`
 
 
 .. _custom_constructors:

include/pybind11/cast.h

@@ -985,6 +985,7 @@ struct copyable_holder_caster<
 
     std::weak_ptr<type> potentially_slicing_weak_ptr() {
         if (typeinfo->holder_enum_v == detail::holder_enum_t::smart_holder) {
+            // Reusing shared_ptr code to minimize code complexity.
             shared_ptr_storage
                 = sh_load_helper.load_as_shared_ptr(value,
                                                     /*responsible_parent=*/nullptr,
@@ -1094,17 +1095,17 @@ PYBIND11_NAMESPACE_END(detail)
 /// does NOT keep any derived Python objects alive (see issue #1333).
 ///
 /// For class_-wrapped types using std::shared_ptr as the holder, the following expressions
-/// produce equivalent results (see tests/test_potentially_slicing_shared_ptr.cpp,py):
+/// produce equivalent results (see tests/test_potentially_slicing_weak_ptr.cpp,py):
 ///
 ///     - obj.cast<std::shared_ptr<T>>()
-///     - py::potentially_slicing_shared_ptr<T>(obj)
+///     - py::potentially_slicing_weak_ptr<T>(obj).lock()
 ///
 /// For class_-wrapped types with trampolines and using py::smart_holder, obj.cast<>()
 /// produces a std::shared_ptr that keeps any derived Python objects alive for its own lifetime,
 /// but this is achieved by introducing a std::shared_ptr control block that is independent of
 /// the one owned by the py::smart_holder. This can lead to surprising std::weak_ptr behavior
-/// (see issue #5623). An easy solution is to use py::potentially_slicing_shared_ptr<>(obj),
-/// as exercised in tests/test_potentially_slicing_shared_ptr.cpp,py (look for
+/// (see issue #5623). An easy solution is to use py::potentially_slicing_weak_ptr<>(obj),
+/// as exercised in tests/test_potentially_slicing_weak_ptr.cpp,py (look for
 /// "set_wp_potentially_slicing"). Note, however, that this reintroduces the inheritance
 /// slicing issue (see issue #1333). The ideal — but usually more involved — solution is to use
 /// a Python weakref to the derived Python object, instead of a C++ base-class std::weak_ptr.

tests/test_potentially_slicing_weak_ptr.cpp

@@ -69,6 +69,8 @@ std::shared_ptr<VB> rtrn_obj_cast_shared_ptr(py::handle obj) {
     return obj.cast<std::shared_ptr<VB>>();
 }
 
+// There is no type_caster<std::weak_ptr<VB>>, and to minimize code complexity
+// we do not want to add one, therefore we have to return a shared_ptr here.
 template <typename VB>
 std::shared_ptr<VB> rtrn_potentially_slicing_shared_ptr(py::handle obj) {
     return py::potentially_slicing_weak_ptr<VB>(obj).lock();