From 14a955c5ebcfd8681603863f23d694fa227687ae Mon Sep 17 00:00:00 2001
From: Christian Hughes <9044780+ItsDoot@users.noreply.github.com>
Date: Thu, 16 Jan 2025 19:18:22 -0600
Subject: [PATCH] Add usage notes for the `IntoX` family of ECS traits (#17379)

# Objective

Occasionally bevy users will want to store systems or observer systems
in a component or resource, but they first try to store `IntoSystem`
instead of `System`, which leads to some headaches having to deal with
the `M` marker type parameter. We should recommend they use the `X`
trait instead of the `IntoX` trait in that case, as well for returning
from a function.

## Solution

Add usage notes to the `IntoX` traits about using `X` instead.
---
 crates/bevy_ecs/src/schedule/config.rs        | 12 ++++++++++++
 crates/bevy_ecs/src/schedule/set.rs           |  6 ++++++
 crates/bevy_ecs/src/system/mod.rs             |  6 ++++++
 crates/bevy_ecs/src/system/observer_system.rs |  6 ++++++
 4 files changed, 30 insertions(+)

diff --git a/crates/bevy_ecs/src/schedule/config.rs b/crates/bevy_ecs/src/schedule/config.rs
index 20308578a4..3d9deeceff 100644
--- a/crates/bevy_ecs/src/schedule/config.rs
+++ b/crates/bevy_ecs/src/schedule/config.rs
@@ -247,6 +247,12 @@ impl<T> NodeConfigs<T> {
 /// [`SystemParam`](crate::system::SystemParam)), or tuples thereof.
 /// It is a common entry point for system configurations.
 ///
+/// # Usage notes
+///
+/// This trait should only be used as a bound for trait implementations or as an
+/// argument to a function. If system configs need to be returned from a
+/// function or stored somewhere, use [`SystemConfigs`] instead of this trait.
+///
 /// # Examples
 ///
 /// ```
@@ -617,6 +623,12 @@ impl SystemSetConfig {
 pub type SystemSetConfigs = NodeConfigs<InternedSystemSet>;
 
 /// Types that can convert into a [`SystemSetConfigs`].
+///
+/// # Usage notes
+///
+/// This trait should only be used as a bound for trait implementations or as an
+/// argument to a function. If system set configs need to be returned from a
+/// function or stored somewhere, use [`SystemSetConfigs`] instead of this trait.
 #[diagnostic::on_unimplemented(
     message = "`{Self}` does not describe a valid system set configuration",
     label = "invalid system set configuration"
diff --git a/crates/bevy_ecs/src/schedule/set.rs b/crates/bevy_ecs/src/schedule/set.rs
index cbe1011e78..623e0a2211 100644
--- a/crates/bevy_ecs/src/schedule/set.rs
+++ b/crates/bevy_ecs/src/schedule/set.rs
@@ -152,6 +152,12 @@ impl SystemSet for AnonymousSet {
 }
 
 /// Types that can be converted into a [`SystemSet`].
+///
+/// # Usage notes
+///
+/// This trait should only be used as a bound for trait implementations or as an
+/// argument to a function. If a system set needs to be returned from a function
+/// or stored somewhere, use [`SystemSet`] instead of this trait.
 #[diagnostic::on_unimplemented(
     message = "`{Self}` is not a system set",
     label = "invalid system set"
diff --git a/crates/bevy_ecs/src/system/mod.rs b/crates/bevy_ecs/src/system/mod.rs
index 360ed03c9b..72dcbfb11e 100644
--- a/crates/bevy_ecs/src/system/mod.rs
+++ b/crates/bevy_ecs/src/system/mod.rs
@@ -160,6 +160,12 @@ use crate::world::World;
 /// Use this to get a system from a function. Also note that every system implements this trait as
 /// well.
 ///
+/// # Usage notes
+///
+/// This trait should only be used as a bound for trait implementations or as an
+/// argument to a function. If a system needs to be returned from a function or
+/// stored somewhere, use [`System`] instead of this trait.
+///
 /// # Examples
 ///
 /// ```
diff --git a/crates/bevy_ecs/src/system/observer_system.rs b/crates/bevy_ecs/src/system/observer_system.rs
index aa247d4939..fa4f6035b8 100644
--- a/crates/bevy_ecs/src/system/observer_system.rs
+++ b/crates/bevy_ecs/src/system/observer_system.rs
@@ -21,6 +21,12 @@ impl<
 }
 
 /// Implemented for systems that convert into [`ObserverSystem`].
+///
+/// # Usage notes
+///
+/// This trait should only be used as a bound for trait implementations or as an
+/// argument to a function. If an observer system needs to be returned from a
+/// function or stored somewhere, use [`ObserverSystem`] instead of this trait.
 #[diagnostic::on_unimplemented(
     message = "`{Self}` cannot become an `ObserverSystem`",
     label = "the trait `IntoObserverSystem` is not implemented",