From 85c8fb9dfa53b0d569c8d583d7e84665fdad4f68 Mon Sep 17 00:00:00 2001
From: JoJoJet <21144246+JoJoJet@users.noreply.github.com>
Date: Fri, 3 Mar 2023 14:43:54 +0000
Subject: [PATCH] Revise docs for system set marker traits (#7882)

# Objective

#7863 introduced a potential footgun. When trying to incorrectly add a user-defined type using `in_base_set`, the compiler will suggest that the user implement `BaseSystemSet` for their type. This is a reasonable-sounding suggestion, however this is not the correct way to make a base set, and will lead to a confusing panic message when a marker trait is implemented for the wrong type.

## Solution

Rewrite the documentation for these traits, making it more clear that `BaseSystemSet` is a marker for types that are already base sets, and not a way to define a base set.
---
 crates/bevy_ecs/src/schedule/set.rs | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/crates/bevy_ecs/src/schedule/set.rs b/crates/bevy_ecs/src/schedule/set.rs
index ad882f11c1..23058a3de9 100644
--- a/crates/bevy_ecs/src/schedule/set.rs
+++ b/crates/bevy_ecs/src/schedule/set.rs
@@ -37,14 +37,18 @@ pub trait SystemSet: DynHash + Debug + Send + Sync + 'static {
     fn dyn_clone(&self) -> Box<dyn SystemSet>;
 }
 
-/// A system set that is never contained in another set.
-/// Systems and other system sets may only belong to one base set.
+/// A marker trait for `SystemSet` types where [`is_base`] returns `true`.
+/// This should only be implemented for types that satisfy this requirement.
+/// It is automatically implemented for base set types by `#[derive(SystemSet)]`.
 ///
-/// This should only be implemented for types that return `true` from [`SystemSet::is_base`].
+/// [`is_base`]: SystemSet::is_base
 pub trait BaseSystemSet: SystemSet {}
 
-/// System sets that are *not* base sets. This should not be implemented for
-/// any types that implement [`BaseSystemSet`].
+/// A marker trait for `SystemSet` types where [`is_base`] returns `false`.
+/// This should only be implemented for types that satisfy this requirement.
+/// It is automatically implemented for non-base set types by `#[derive(SystemSet)]`.
+///
+/// [`is_base`]: SystemSet::is_base
 pub trait FreeSystemSet: SystemSet {}
 
 impl PartialEq for dyn SystemSet {