From 75090647cea463e4e43914e404674cb1b8b47a13 Mon Sep 17 00:00:00 2001
From: "Ralf W. Grosse-Kunstleve" <rwgk@google.com>
Date: Mon, 12 Jul 2021 16:56:10 -0700
Subject: [PATCH] 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 | 7 ++++---
 tests/test_stl.cpp          | 6 ++++++
 tests/test_stl.py           | 7 +++++++
 3 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst
index d880008b0..a537cb65e 100644
--- a/docs/advanced/functions.rst
+++ b/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:
diff --git a/tests/test_stl.cpp b/tests/test_stl.cpp
index 1f308e139..eb8cdab7b 100644
--- a/tests/test_stl.cpp
+++ b/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);
 }
diff --git a/tests/test_stl.py b/tests/test_stl.py
index 96939257c..5fd3570fa 100644
--- a/tests/test_stl.py
+++ b/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