Suggest smart_holder for "most situations for safety"

pybind · Mar 1, 2025 · e83f3eb · e83f3eb
1 parent 8409b19
commit e83f3eb
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 6 deletions.
diff --git a/docs/advanced/smart_ptrs.rst b/docs/advanced/smart_ptrs.rst
@@ -31,10 +31,12 @@ simply add ``py::smart_holder`` to ``py::class_``:
 
 .. note::
 
-    A shorthand, ``py::classh<T>``, is provided for ``py::class_<T,
-    py::smart_holder>``. The ``h`` in ``py::classh`` comes from
-    **smart_holder** but is condensed for brevity; it is the same number of
-    characters as ``py::class_``.
+    A shorthand, ``py::classh<T>``, is provided for
+    ``py::class_<T, py::smart_holder>``. The ``h`` in ``py::classh`` stands
+    for **smart_holder** but is shortened for brevity, ensuring it has the
+    same number of characters as ``py::class_``. This design choice facilitates
+    easy experimentation with ``py::smart_holder`` without introducing
+    distracting whitespace noise in diffs.
 
 The ``py::smart_holder`` functionality includes the following:
 

diff --git a/docs/classes.rst b/docs/classes.rst
@@ -42,8 +42,8 @@ constructor (see the :ref:`custom_constructors` section for details).
 .. note::
 
     Starting with pybind11v3, it is recommended to include `py::smart_holder`
-    if you plan to support conversions to C++ smart pointers. See
-    :ref:`smart_holder` for more information.
+    in most situations for safety, especially if you plan to support conversions
+    to C++ smart pointers. See :ref:`smart_holder` for more information.
 
 An interactive Python session demonstrating this example is shown below: