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.

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);
 }