Improve type hinting docs for sync_compatible

[benjamincerigo]

This PR aims to improve the docs so that if a user is typing the return of a function that is decorated by @sync_compatible they are aware of its behaviour.

It is a quick fix for the issue:
Closes: #15275

[codspeed-hq]

CodSpeed Performance Report

Merging #15327 will not alter performance

_{Comparing benjamincerigo:improve-doc-mypy-sync (5e34445) with main (6e9adb8)}

Summary

✅ 3 untouched benchmarks

[desertaxle]

Thanks for the PR @benjamincerigo! I've suggested an alternate wording for clarity, but this comment will be very useful for future developers!

[desertaxle]

Suggested change

	When adding type hints for functions that are decorated with `@sync_compatible` mypy will infer
	the return type as if the function is sync: the return type on the wrapped function rather then
	a coroutine. If you want to handle coroutines yourself you will need to ignore the types and
	"cast" the return type to a coroutine. For example:
	```python
	result: Coroutine = sync_compatible(my_async_function)(arg1, arg2) # type: ignore
	```
	Note: Type checkers will infer functions decorated with `@sync_compatible` are synchronous. If you want to use the decorated function in an async context, you will need to ignore the types and
	"cast" the return type to a coroutine. For example:
	```python
	result: Coroutine = sync_compatible(my_async_function)(arg1, arg2) # type: ignore
	```

[benjamincerigo]

@desertaxle thanks for the suggestions, I have fixed this up.

[desertaxle]

Thank you!