improve documentation for macro-generated label types (#5367)

# Objective

I noticed while working on #5366 that the documentation for label types wasn't working correctly. Having experimented with this for a few weeks, I believe that generating docs in macros is more effort than it's worth.

## Solution

Add more boilerplate, copy-paste and edit the docs across types. This also lets us add custom doctests for specific types. Also, we don't need `concat_idents` as a dependency anymore.

crates/bevy_app/src/app.rs

@@ -15,7 +15,12 @@ use std::fmt::Debug;
 
 #[cfg(feature = "trace")]
 use bevy_utils::tracing::info_span;
-bevy_utils::define_label!(AppLabel);
+bevy_utils::define_label!(
+    /// A strongly-typed class of labels used to identify an [`App`].
+    AppLabel,
+    /// A strongly-typed identifier for an [`AppLabel`].
+    AppLabelId,
+);
 
 #[allow(clippy::needless_doctest_main)]
 /// A container of app logic and data.

crates/bevy_ecs/src/schedule/label.rs

@@ -1,7 +1,27 @@
 pub use bevy_ecs_macros::{AmbiguitySetLabel, RunCriteriaLabel, StageLabel, SystemLabel};
 use bevy_utils::define_label;
 
-define_label!(StageLabel);
+define_label!(
-define_label!(SystemLabel);
+    /// A strongly-typed class of labels used to identify [`Stage`](crate::schedule::Stage)s.
-define_label!(AmbiguitySetLabel);
+    StageLabel,
-define_label!(RunCriteriaLabel);
+    /// Strongly-typed identifier for a [`StageLabel`].
+    StageLabelId,
+);
+define_label!(
+    /// A strongly-typed class of labels used to identify [`System`](crate::system::System)s.
+    SystemLabel,
+    /// Strongly-typed identifier for a [`SystemLabel`].
+    SystemLabelId,
+);
+define_label!(
+    /// A strongly-typed class of labels used to identify sets of systems with intentionally ambiguous execution order.
+    AmbiguitySetLabel,
+    /// Strongly-typed identifier for an [`AmbiguitySetLabel`].
+    AmbiguitySetLabelId,
+);
+define_label!(
+    /// A strongly-typed class of labels used to identify [run criteria](crate::schedule::RunCriteria).
+    RunCriteriaLabel,
+    /// Strongly-typed identifier for a [`RunCriteriaLabel`].
+    RunCriteriaLabelId,
+);

crates/bevy_utils/Cargo.toml

@@ -14,7 +14,6 @@ tracing = { version = "0.1", default-features = false, features = ["std"] }
 instant = { version = "0.1", features = ["wasm-bindgen"] }
 uuid = { version = "1.1", features = ["v4", "serde"] }
 hashbrown = { version = "0.12", features = ["serde"] }
-concat-idents = "1"
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 getrandom = {version = "0.2.0", features = ["js"]}

crates/bevy_utils/src/label.rs

@@ -47,70 +47,73 @@ where
     }
 }
 
-#[doc(hidden)]
-pub use concat_idents::concat_idents;
-
 /// Macro to define a new label trait
 ///
 /// # Example
 ///
 /// ```
 /// # use bevy_utils::define_label;
-/// define_label!(MyNewLabelTrait);
+/// define_label!(
+///     /// A class of labels.
+///     MyNewLabelTrait,
+///     /// Identifies a value that implements `MyNewLabelTrait`.
+///     MyNewLabelId,
+/// );
 /// ```
 #[macro_export]
 macro_rules! define_label {
-    ($label_name:ident) => {
+    (
-        $crate::label::concat_idents!(id_name = $label_name, Id {
+        $(#[$label_attr:meta])*
+        $label_name:ident,
 
-            /// Stores one of a set of strongly-typed labels for a class of objects.
+        $(#[$id_attr:meta])*
-            #[derive(Clone, Copy, PartialEq, Eq, Hash)]
+        $id_name:ident $(,)?
-            pub struct id_name(::core::any::TypeId, &'static str);
+    ) => {
+        $(#[$id_attr])*
+        #[derive(Clone, Copy, PartialEq, Eq, Hash)]
+        pub struct $id_name(::core::any::TypeId, &'static str);
 
-            impl ::core::fmt::Debug for id_name {
+        impl ::core::fmt::Debug for $id_name {
-                fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
+            fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
-                    write!(f, "{}", self.1)
+                write!(f, "{}", self.1)
-                }
             }
+        }
 
-            /// Types that can be converted to a(n) [`id_name`].
+        $(#[$label_attr])*
+        pub trait $label_name: 'static {
+            /// Converts this type into an opaque, strongly-typed label.
+            fn as_label(&self) -> $id_name {
+                let id = self.type_id();
+                let label = self.as_str();
+                $id_name(id, label)
+            }
+            /// Returns the [`TypeId`] used to differentiate labels.
+            fn type_id(&self) -> ::core::any::TypeId {
+                ::core::any::TypeId::of::<Self>()
+            }
+            /// Returns the representation of this label as a string literal.
             ///
-            /// Check the docs for [`define_label`](bevy_ecs::define_label) for more info.
+            /// In cases where you absolutely need a label to be determined at runtime,
-            pub trait $label_name: 'static {
+            /// you can use [`Box::leak`] to get a `'static` reference.
-                /// Converts this type into an opaque, strongly-typed label.
+            fn as_str(&self) -> &'static str;
-                fn as_label(&self) -> id_name {
+        }
-                    let id = self.type_id();
-                    let label = self.as_str();
-                    id_name(id, label)
-                }
-                /// Returns the [`TypeId`] used to differentiate labels.
-                fn type_id(&self) -> ::core::any::TypeId {
-                    ::core::any::TypeId::of::<Self>()
-                }
-                /// Returns the representation of this label as a string literal.
-                ///
-                /// In cases where you absolutely need a label to be determined at runtime,
-                /// you can use [`Box::leak`] to get a `'static` reference.
-                fn as_str(&self) -> &'static str;
-            }
 
-            impl $label_name for id_name {
+        impl $label_name for $id_name {
-                fn as_label(&self) -> Self {
+            fn as_label(&self) -> Self {
-                    *self
+                *self
-                }
-                fn type_id(&self) -> ::core::any::TypeId {
-                    self.0
-                }
-                fn as_str(&self) -> &'static str {
-                    self.1
-                }
             }
+            fn type_id(&self) -> ::core::any::TypeId {
+                self.0
+            }
+            fn as_str(&self) -> &'static str {
+                self.1
+            }
+        }
 
-            impl $label_name for &'static str {
+        impl $label_name for &'static str {
-                fn as_str(&self) -> Self {
+            fn as_str(&self) -> Self {
-                    self
+                self
-                }
             }
-        });
+        }
     };
 }