From 02cb1a8d7153cbfeabc68cb69169a62c42ca8403 Mon Sep 17 00:00:00 2001 From: JoJoJet Date: Wed, 20 Jul 2022 19:39:42 +0000 Subject: [PATCH] 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 | 7 +- crates/bevy_ecs/src/schedule/label.rs | 28 ++++++- crates/bevy_utils/Cargo.toml | 1 - crates/bevy_utils/src/label.rs | 101 +++++++++++++------------- 4 files changed, 82 insertions(+), 55 deletions(-) diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index 0e717ca632e269..e9166bc3dd5732 100644 --- a/crates/bevy_app/src/app.rs +++ b/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. diff --git a/crates/bevy_ecs/src/schedule/label.rs b/crates/bevy_ecs/src/schedule/label.rs index 28d6c10b3b2809..c9bccf8303084a 100644 --- a/crates/bevy_ecs/src/schedule/label.rs +++ b/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!(SystemLabel); -define_label!(AmbiguitySetLabel); -define_label!(RunCriteriaLabel); +define_label!( + /// A strongly-typed class of labels used to identify [`Stage`](crate::schedule::Stage)s. + StageLabel, + /// 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, +); diff --git a/crates/bevy_utils/Cargo.toml b/crates/bevy_utils/Cargo.toml index 2e0b45eac13b59..701b2c301191a2 100644 --- a/crates/bevy_utils/Cargo.toml +++ b/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"]} diff --git a/crates/bevy_utils/src/label.rs b/crates/bevy_utils/src/label.rs index a66d3a03680f15..835656569c1fea 100644 --- a/crates/bevy_utils/src/label.rs +++ b/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 { - - /// Stores one of a set of strongly-typed labels for a class of objects. - #[derive(Clone, Copy, PartialEq, Eq, Hash)] - pub struct id_name(::core::any::TypeId, &'static str); - - impl ::core::fmt::Debug for id_name { - fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result { - write!(f, "{}", self.1) - } + ( + $(#[$label_attr:meta])* + $label_name:ident, + + $(#[$id_attr:meta])* + $id_name:ident $(,)? + ) => { + $(#[$id_attr])* + #[derive(Clone, Copy, PartialEq, Eq, Hash)] + pub struct $id_name(::core::any::TypeId, &'static str); + + impl ::core::fmt::Debug for $id_name { + fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result { + write!(f, "{}", self.1) } + } - /// Types that can be converted to a(n) [`id_name`]. - /// - /// Check the docs for [`define_label`](bevy_ecs::define_label) for more info. - 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::() - } - /// 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; + $(#[$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::() } + /// 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 { - fn as_label(&self) -> Self { - *self - } - fn type_id(&self) -> ::core::any::TypeId { - self.0 - } - fn as_str(&self) -> &'static str { - self.1 - } + impl $label_name for $id_name { + fn as_label(&self) -> Self { + *self + } + fn type_id(&self) -> ::core::any::TypeId { + self.0 } + fn as_str(&self) -> &'static str { + self.1 + } + } - impl $label_name for &'static str { - fn as_str(&self) -> Self { - self - } + impl $label_name for &'static str { + fn as_str(&self) -> Self { + self } - }); + } }; }