From bc373b52d1de851d3c687e31a4860edc9f05ca56 Mon Sep 17 00:00:00 2001
From: sobolevn <mail@sobolevn.me>
Date: Thu, 19 Sep 2024 11:09:00 +0300
Subject: [PATCH] gh-124234: Improve docs for `Mock.reset_mock`

---
 Doc/library/unittest.mock.rst | 43 +++++++++++++++++++++++++++--------
 1 file changed, 33 insertions(+), 10 deletions(-)

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index e15f8a4e903dc5..ef5e50eab23d1e 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -401,6 +401,8 @@ the *new_callable* argument to :func:`patch`.
 
         The reset_mock method resets all the call attributes on a mock object:
 
+        .. doctest::
+
             >>> mock = Mock(return_value=None)
             >>> mock('hello')
             >>> mock.called
@@ -409,20 +411,41 @@ the *new_callable* argument to :func:`patch`.
             >>> mock.called
             False
 
-        .. versionchanged:: 3.6
-           Added two keyword-only arguments to the reset_mock function.
-
         This can be useful where you want to make a series of assertions that
-        reuse the same object. Note that :meth:`reset_mock` *doesn't* clear the
+        reuse the same object.
+
+        *return_value* parameter when set to ``True`` resets :attr:`return_value`:
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=5)
+            >>> mock('hello')
+            5
+            >>> mock.reset_mock(return_value=True)
+            >>> mock('hello')  # doctest: +ELLIPSIS
+            <Mock name='mock()' id='...'>
+
+        *side_effect* parameter when set to ``True`` resets :attr:`side_effect`:
+
+        .. doctest::
+
+            >>> mock = Mock(side_effect=ValueError)
+            >>> mock('hello')
+            Traceback (most recent call last):
+              ...
+            ValueError
+            >>> mock.reset_mock(side_effect=True)
+            >>> mock('hello')  # doctest: +ELLIPSIS
+            <Mock name='mock()' id='...'>
+
+        Note that :meth:`reset_mock` *doesn't* clear the
         :attr:`return_value`, :attr:`side_effect` or any child attributes you have
-        set using normal assignment by default. In case you want to reset
-        :attr:`return_value` or :attr:`side_effect`, then pass the corresponding
-        parameter as ``True``. Child mocks and the return value mock
-        (if any) are reset as well.
+        set using normal assignment by default.
 
-        .. note:: *return_value*, and *side_effect* are keyword-only
-                  arguments.
+        Child mocks are reset as well.
 
+        .. versionchanged:: 3.6
+           Added two keyword-only arguments to the reset_mock function.
 
     .. method:: mock_add_spec(spec, spec_set=False)