Deprecate upcasting methods for reflection

[alice-i-cecile]

Objective

• These methods are no longer needed: this is now a Rust language feature.
• I would like to improve the reflection docs and this was bugging me.
• Fixes Remove dedicated methods for upcasting from bevy_reflect #21634.

Solution

1. Deprecate the methods.
2. Fix the docs.
3. Remove internal usages.
4. Add a migration guide.

Testing

No more deprecation warnings!

[hymm]

looks good. I'm fine with leaving deprecating the any methods to an issue.

[alice-i-cecile]

I've gone ahead and removed the Any downcasting methods too while we're here. Good eye!

[alice-i-cecile]

Splitting this out explicitly is required to disambiguate and avoid infinite recursion.

[hymm]

Changes look good.

[kaoet]

These removed docs are for PartialReflect::*, which are not deprecated in this PR.

[alice-i-cecile]

I'm getting a number of stack overflows, but I can't quite figure out what's going wrong. I would appreciate a hand spotting where I've made a mistake.

Moving to a very explicit set of changes that explicitly coerces everywhere is probably best, but I would prefer to have a better understanding rather than just blindly making this change.

[kaoet]

I'm getting a number of stack overflows, but I can't quite figure out what's going wrong. I would appreciate a hand spotting where I've made a mistake.

The stack overflow is caused by downcast() in impl dyn Reflect calling itself.

BUT. When I tried to fix that function, several tests under bevy_reflect start to fail. One example is tests::should_reflect_remote_value_type.

It seems that as_any, as_any_mut, and into_any are not always equivalent to coercion and should not be deprecated. As the doc of them says, they have special behavior for remote wrapper types.

bevy/crates/bevy_reflect/derive/src/impls/common.rs

Lines 17 to 30 in d87d491

	#[inline]
	fn into_any(self: #bevy_reflect_path::__macro_exports::alloc_utils::Box<Self>) -> #bevy_reflect_path::__macro_exports::alloc_utils::Box<dyn #FQAny> {
	#bevy_reflect_path::__macro_exports::alloc_utils::Box::new(self.0)
	}
	#[inline]
	fn as_any(&self) -> &dyn #FQAny {
	&self.0
	}
	#[inline]
	fn as_any_mut(&mut self) -> &mut dyn #FQAny {
	&mut self.0
	}

Sorry for suggesting deprecating them at first. 🤣