More precise return_value_policy::automatic documentation. (#2920)

* Adding test_return_vector_bool_raw_ptr to test_stl.py.

* First attempt to make the documentation more accurate, but not trying to be comprehensive, to not bloat the reference table with too many details.

* Fixing minor oversights.

* Applying reviewer suggestion.

docs/advanced/functions.rst

@@ -90,17 +90,18 @@ The following table provides an overview of available policies:
 |                                                  | return value is referenced by Python. This is the default policy for       |
 |                                                  | property getters created via ``def_property``, ``def_readwrite``, etc.     |
 +--------------------------------------------------+----------------------------------------------------------------------------+
-| :enum:`return_value_policy::automatic`           | **Default policy.** This policy falls back to the policy                   |
+| :enum:`return_value_policy::automatic`           | This policy falls back to the policy                                       |
 |                                                  | :enum:`return_value_policy::take_ownership` when the return value is a     |
 |                                                  | pointer. Otherwise, it uses :enum:`return_value_policy::move` or           |
 |                                                  | :enum:`return_value_policy::copy` for rvalue and lvalue references,        |
 |                                                  | respectively. See above for a description of what all of these different   |
-|                                                  | policies do.                                                               |
+|                                                  | policies do. This is the default policy for ``py::class_``-wrapped types.  |
 +--------------------------------------------------+----------------------------------------------------------------------------+
 | :enum:`return_value_policy::automatic_reference` | As above, but use policy :enum:`return_value_policy::reference` when the   |
 |                                                  | return value is a pointer. This is the default conversion policy for       |
 |                                                  | function arguments when calling Python functions manually from C++ code    |
-|                                                  | (i.e. via handle::operator()). You probably won't need to use this.        |
+|                                                  | (i.e. via ``handle::operator()``) and the casters in ``pybind11/stl.h``.   |
+|                                                  | You probably won't need to use this explicitly.                            |
 +--------------------------------------------------+----------------------------------------------------------------------------+
 
 Return value policies can also be applied to properties:

tests/test_stl.cpp

@@ -334,4 +334,10 @@ TEST_SUBMODULE(stl, m) {
     py::class_<Issue1561Outer>(m, "Issue1561Outer")
         .def(py::init<>())
         .def_readwrite("list", &Issue1561Outer::list);
+
+    m.def(
+        "return_vector_bool_raw_ptr",
+        []() { return new std::vector<bool>(4513); },
+        // Without explicitly specifying `take_ownership`, this function leaks.
+        py::return_value_policy::take_ownership);
 }

tests/test_stl.py

@@ -283,3 +283,10 @@ def test_issue_1561():
     bar.list = [m.Issue1561Inner("bar")]
     bar.list
     assert bar.list[0].data == "bar"
+
+
+def test_return_vector_bool_raw_ptr():
+    # Add `while True:` for manual leak checking.
+    v = m.return_vector_bool_raw_ptr()
+    assert isinstance(v, list)
+    assert len(v) == 4513