Doc unclear that ensure_future should also have its referenced saved somewhere

[ilan-schemoul]

Documentation

It will seem silly to some but the way the doc is written I was positive "Save a reference to the result of this function, to avoid a task disappearing mid-execution." applied to only create_task :

As the note first reads about create_task I thought the "this" in "Save a reference to the result of this function" applied to create_tasks only.

We should reverse the order of the notes.

I'm sure some people would believe this to be a non issue but I have worked multiple times with ensure_future, and read this doc a few times, and me and even my senior coworkers (10 years in the company) seemed positive the note applied to create_tasks.
As tasks being destroyed, kinda randomly, by the GC can be a bug that can have profound consequences and can be really hard to debug I hope this matter will be taken seriously.
It's a struck of luck that I realized that the note applied to ensure_future and it took me hours of research to realize that it's likeley that the note also applies to ensure_future

Linked PRs

• gh-129169: Update docs on asyncio.ensure_future() to make it more clear that a reference of the returned value should be stored and provide an alternative to avoid this. #129986

[graingert]

Possibly while we are upgrading this warning we should link to TaskGroup.create_task which keeps a reference to the task for you