Clarify event_loop fixture deprecation

docs/reference/changelog.rst

@@ -6,6 +6,7 @@ Changelog
 ===================
 - Fixes an issue that caused a broken event loop when a function-scoped test was executed in between two tests with wider loop scope `#950 <https://github.com/pytest-dev/pytest-asyncio/issues/950>`_
 - Improves test collection speed in auto mode `#1020 <https://github.com/pytest-dev/pytest-asyncio/pull/1020>`_
+- Corrects the warning that is emitted upon redefining the event_loop fixture
 
 
 0.25.0 (2024-12-13)

docs/reference/fixtures/index.rst

@@ -4,6 +4,13 @@ Fixtures
 
 event_loop
 ==========
+*This fixture is deprecated.*
+
+*If you want to request an asyncio event loop with a scope other than function
+scope, use the "loop_scope" argument to* :ref:`reference/markers/asyncio` *when marking the tests.
+If you want to return different types of event loops, use the* :ref:`reference/fixtures/event_loop_policy`
+*fixture.*
+
 Creates a new asyncio event loop based on the current event loop policy. The new loop
 is available as the return value of this fixture for synchronous functions, or via `asyncio.get_running_loop <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.get_running_loop>`__ for asynchronous functions.
 The event loop is closed when the fixture scope ends.
@@ -12,14 +19,16 @@ The fixture scope defaults to ``function`` scope.
 .. include:: event_loop_example.py
     :code: python
 
-Note that, when using the ``event_loop`` fixture, you need to interact with the event loop using methods like ``event_loop.run_until_complete``. If you want to *await* code inside your test function, you need to write a coroutine and use it as a test function. The `asyncio <#pytest-mark-asyncio>`__ marker
+Note that, when using the ``event_loop`` fixture, you need to interact with the event loop using methods like ``event_loop.run_until_complete``. If you want to *await* code inside your test function, you need to write a coroutine and use it as a test function. The :ref:`asyncio <reference/markers/asyncio>` marker
 is used to mark coroutines that should be treated as test functions.
 
 If you need to change the type of the event loop, prefer setting a custom event loop policy over redefining the ``event_loop`` fixture.
 
 If the ``pytest.mark.asyncio`` decorator is applied to a test function, the ``event_loop``
 fixture will be requested automatically by the test function.
 
+.. _reference/fixtures/event_loop_policy:
+
 event_loop_policy
 =================
 Returns the event loop policy used to create asyncio event loops.

docs/reference/markers/index.rst

@@ -2,6 +2,8 @@
 Markers
 =======
 
+.. _reference/markers/asyncio:
+
 ``pytest.mark.asyncio``
 =======================
 A coroutine or async generator with this marker is treated as a test function by pytest.

pytest_asyncio/plugin.py

@@ -794,7 +794,7 @@ def _temporary_event_loop_policy(policy: AbstractEventLoopPolicy) -> Iterator[No
     Replacing the event_loop fixture with a custom implementation is deprecated
     and will lead to errors in the future.
     If you want to request an asyncio event loop with a scope other than function
-    scope, use the "scope" argument to the asyncio mark when marking the tests.
+    scope, use the "loop_scope" argument to the asyncio mark when marking the tests.
     If you want to return different types of event loops, use the event_loop_policy
     fixture.
     """