gh-124234: Improve docs for `Mock.reset_mock` (#124237)

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,21 +411,42 @@ the *new_callable* argument to :func:`patch`.
             >>> mock.called
             False
 
+        This can be useful where you want to make a series of assertions that
+        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.
+
+        Child mocks are reset as well.
+
         .. 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
-        :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.
-
-        .. note:: *return_value*, and *side_effect* are keyword-only
-                  arguments.
-
-
     .. method:: mock_add_spec(spec, spec_set=False)
 
         Add a spec to a mock. *spec* can either be an object or a

Lib/unittest/mock.py

@@ -628,7 +628,9 @@ class NonCallableMock(Base):
     side_effect = property(__get_side_effect, __set_side_effect)
 
 
-    def reset_mock(self, visited=None, *, return_value=False, side_effect=False):
+    def reset_mock(self, visited=None, *,
+                   return_value: bool = False,
+                   side_effect: bool = False):
         "Restore the mock object to its initial state."
         if visited is None:
             visited = []
@@ -2218,7 +2220,7 @@ class MagicMock(MagicMixin, Mock):
         self._mock_add_spec(spec, spec_set)
         self._mock_set_magics()
 
-    def reset_mock(self, /, *args, return_value=False, **kwargs):
+    def reset_mock(self, /, *args, return_value: bool = False, **kwargs):
         if (
             return_value
             and self._mock_name