@picnixz, could you please re-review? :)

(The force-push was intentional; I know this is discouraged but I want to save noise, you can still follow what happened.)

Documentation build overview

📚 cpython-previews | 🛠️ Build #33748676 | 📁 Comparing b0ae4d1 against main (1f649fe)

  🔍 Preview build  

± Modified

• c-api/type.html
• deprecations/index.html
• deprecations/pending-removal-in-3.18.html
• library/annotationlib.html
• library/asyncio-subprocess.html
• library/csv.html
• library/ctypes.html
• library/exceptions.html
• library/functools.html
• library/logging.handlers.html
• and 10 more...

I'm not sure it's valuable to specifically disallow return annotations if we still allow dispatching by annotations on wrong parameters.

We could deprecate cases when the chosen parameter isn't the same as in my new formula. @picnixz prefers to just document the limitation. And when the deprecation ends, we break custom descriptors that emulate static method behavior (which nowadays seems less of a risk than I originally thought, case looks extremely rare and it's a trivial fix).

I'm not sure it's valuable to specifically disallow return annotations if we still allow dispatching by annotations on wrong parameters.

Yeah, it's not very valuable. But in other cases we can't really be sure something is wrong, and the check is cheap. +0; I'd merge it.

New deprecations should not get backported. The docs improvements will need manual backports.