doc fixes; system ambiguity fixes

Author: UkoeHB

crates/bevy_text/src/font_atlas_set.rs

@@ -60,9 +60,9 @@ pub struct FontAtlasKey(pub u32, pub FontSmoothing);
 /// A `FontAtlasSet` is an [`Asset`].
 ///
 /// There is one `FontAtlasSet` for each font:
-/// - When a [`Font`] is loaded as an asset and then used in [`Text`](crate::Text),
+/// - When a [`Font`] is loaded as an asset and then used in [`TextStyle`](crate::TextStyle),
 ///   a `FontAtlasSet` asset is created from a weak handle to the `Font`.
-/// - ~When a font is loaded as a system font, and then used in [`Text`](crate::Text),
+/// - ~When a font is loaded as a system font, and then used in [`TextStyle`](crate::TextStyle),
 ///   a `FontAtlasSet` asset is created and stored with a strong handle to the `FontAtlasSet`.~
 ///   (*Note that system fonts are not currently supported by the `TextPipeline`.*)
 ///

crates/bevy_text/src/glyph.rs

@@ -13,7 +13,7 @@ use bevy_sprite::TextureAtlasLayout;
 /// Used in [`TextPipeline::queue_text`](crate::TextPipeline::queue_text) and [`crate::TextLayoutInfo`] for rendering glyphs.
 #[derive(Debug, Clone, Reflect)]
 pub struct PositionedGlyph {
-    /// The position of the glyph in the [`Text`](crate::Text)'s bounding box.
+    /// The position of the glyph in the text block's bounding box.
     pub position: Vec2,
     /// The width and height of the glyph in logical pixels.
     pub size: Vec2,

crates/bevy_text/src/lib.rs

@@ -14,7 +14,7 @@
 //!
 //! The [`TextPipeline`] resource does all of the heavy lifting for rendering text.
 //!
-//! [`Text`] is first measured by creating a [`TextMeasureInfo`] in [`TextPipeline::create_text_measure`],
+//! UI `Text` is first measured by creating a [`TextMeasureInfo`] in [`TextPipeline::create_text_measure`],
 //! which is called by the `measure_text_system` system of `bevy_ui`.
 //!
 //! Note that text measurement is only relevant in a UI context.
@@ -23,7 +23,7 @@
 //! or [`text2d::update_text2d_layout`] system (in a 2d world space context)
 //! passes it into [`TextPipeline::queue_text`], which:
 //!
-//! 1. creates a [`Buffer`](cosmic_text::Buffer) from the [`TextSection`]s, generating new [`FontAtlasSet`]s if necessary.
+//! 1. updates a [`Buffer`](cosmic_text::Buffer) from the [`TextSpan`]s, generating new [`FontAtlasSet`]s if necessary.
 //! 2. iterates over each glyph in the [`Buffer`](cosmic_text::Buffer) to create a [`PositionedGlyph`],
 //!    retrieving glyphs from the cache, or rasterizing to a [`FontAtlas`] if necessary.
 //! 3. [`PositionedGlyph`]s are stored in a [`TextLayoutInfo`],
@@ -92,7 +92,7 @@ pub const DEFAULT_FONT_DATA: &[u8] = include_bytes!("FiraMono-subset.ttf");
 pub struct TextPlugin;
 
 /// Text is rendered for two different view projections;
-/// 2-dimensional text ([`Text2dBundle`]) is rendered in "world space" with a `BottomToTop` Y-axis,
+/// 2-dimensional text ([`Text2d`]) is rendered in "world space" with a `BottomToTop` Y-axis,
 /// while UI is rendered with a `TopToBottom` Y-axis.
 /// This matters for text because the glyph positioning is different in either layout.
 /// For `TopToBottom`, 0 is the top of the text, while for `BottomToTop` 0 is the bottom.

crates/bevy_text/src/pipeline.rs

@@ -60,7 +60,7 @@ struct FontFaceInfo {
     family_name: Arc<str>,
 }
 
-/// The `TextPipeline` is used to layout and render [`Text`](crate::Text).
+/// The `TextPipeline` is used to layout and render text blocks (see `Text`/[`Text2d`](crate::Text2d)).
 ///
 /// See the [crate-level documentation](crate) for more information.
 #[derive(Default, Resource)]
@@ -383,9 +383,10 @@ impl TextPipeline {
     }
 }
 
-/// Render information for a corresponding [`Text`](crate::Text) component.
+/// Render information for a corresponding text block.
 ///
-/// Contains scaled glyphs and their size. Generated via [`TextPipeline::queue_text`].
+/// Contains scaled glyphs and their size. Generated via [`TextPipeline::queue_text`] when an entity has
+/// [`TextBlock`] and [`ComputedTextBlock`] components.
 #[derive(Component, Clone, Default, Debug, Reflect)]
 #[reflect(Component, Default, Debug)]
 pub struct TextLayoutInfo {
@@ -395,7 +396,7 @@ pub struct TextLayoutInfo {
     pub size: Vec2,
 }
 
-/// Size information for a corresponding [`Text`](crate::Text) component.
+/// Size information for a corresponding [`ComputedTextBlock`] component.
 ///
 /// Generated via [`TextPipeline::create_text_measure`].
 #[derive(Debug)]

crates/bevy_text/src/text.rs

@@ -76,8 +76,8 @@ impl ComputedTextBlock {
 
     /// Indicates if the text needs to be refreshed in [`TextLayoutInfo`].
     ///
-    /// Updated automatically by [`detect_text_needs_rerender`](crate::detect_text_needs_rerender) and cleared
-    /// by [`TextPipeline`] methods.
+    /// Updated automatically by [`detect_text_needs_rerender`] and cleared
+    /// by [`TextPipeline`](crate::TextPipeline) methods.
     pub fn needs_rerender(&self) -> bool {
         self.needs_rerender
     }
@@ -99,7 +99,7 @@ impl Default for ComputedTextBlock {
 /// spans associated with a text block are collected into [`ComputedTextBlock`] for layout, and then inserted
 /// to [`TextLayoutInfo`] for rendering.
 ///
-/// See [`Text2d`] for the core component of 2d text, and `Text` in `bevy_ui` for UI text.
+/// See [`Text2d`](crate::Text2d) for the core component of 2d text, and `Text` in `bevy_ui` for UI text.
 #[derive(Component, Debug, Copy, Clone, Default, Reflect)]
 #[reflect(Component, Default, Debug)]
 #[require(ComputedTextBlock, TextLayoutInfo)]
@@ -349,8 +349,8 @@ pub enum FontSmoothing {
 
 /// System that detects changes to text blocks and sets `ComputedTextBlock::should_rerender`.
 ///
-/// Generic over the root text component and text span component. For example, [`Text2d`]/[`TextSpan`] for 2d or
-/// `Text`/[`TextSpan`] for UI.
+/// Generic over the root text component and text span component. For example, [`Text2d`](crate::Text2d)/[`TextSpan`] for
+/// 2d or `Text`/[`TextSpan`] for UI.
 pub fn detect_text_needs_rerender<Root: Component>(
     changed_roots: Query<
         Entity,

crates/bevy_text/src/text2d.rs

@@ -38,7 +38,7 @@ use bevy_window::{PrimaryWindow, Window, WindowScaleFactorChanged};
 /// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/2d/text2d.rs)
 ///
 /// The string in this component is the first 'text span' in a hierarchy of text spans that are collected into
-/// a [`TextBlock`]. See [`TextSpan2d`] for the component used by children of entities with [`Text2d`].
+/// a [`TextBlock`]. See [`TextSpan`](crate::TextSpan) for the component used by children of entities with [`Text2d`].
 ///
 /// With `Text2d` the `justify` field of [`TextBlock`] only affects the internal alignment of a block of text and not its
 /// relative position, which is controlled by the [`Anchor`] component.

crates/bevy_text/src/text_access.rs

@@ -42,12 +42,13 @@ impl TextIterScratch {
     }
 }
 
-/// System parameter for reading text spans in a [`TextBlock`].
+/// System parameter for reading text spans in a [`TextBlock`](crate::TextBlock).
 ///
 /// `R` is the root text component, and `S` is the text span component on children.
 #[derive(SystemParam)]
 pub struct TextReader<'w, 's, R: TextRoot> {
-    scratch: ResMut<'w, TextIterScratch>,
+    // This is a local to avoid system ambiguities when TextReaders run in parallel.
+    scratch: Local<'s, TextIterScratch>,
     roots: Query<'w, 's, (&'static R, &'static TextStyle, Option<&'static Children>)>,
     spans: Query<
         'w,
@@ -108,7 +109,7 @@ impl<'w, 's, R: TextRoot> TextReader<'w, 's, R> {
     }
 }
 
-/// Iterator returned by [`TextReader::iter`] and [`TextWriter::iter`].
+/// Iterator returned by [`TextReader::iter`].
 ///
 /// Iterates all spans in a text block according to hierarchy traversal order.
 /// Does *not* flatten interspersed ghost nodes. Only contiguous spans are traversed.
@@ -183,11 +184,12 @@ impl<'a, R: TextRoot> Drop for TextSpanIter<'a, R> {
     }
 }
 
-/// System parameter for reading and writing text spans in a [`TextBlock`].
+/// System parameter for reading and writing text spans in a [`TextBlock`](crate::TextBlock).
 ///
 /// `R` is the root text component, and `S` is the text span component on children.
 #[derive(SystemParam)]
 pub struct TextWriter<'w, 's, R: TextRoot> {
+    // This is a resource because two TextWriters can't run in parallel.
     scratch: ResMut<'w, TextIterScratch>,
     roots: Query<'w, 's, (&'static mut R, &'static mut TextStyle), Without<TextSpan>>,
     spans: Query<'w, 's, (&'static mut TextSpan, &'static mut TextStyle), Without<R>>,

crates/bevy_ui/src/lib.rs

@@ -8,7 +8,7 @@
 
 //! This crate contains Bevy's UI system, which can be used to create UI for both 2D and 3D games
 //! # Basic usage
-//! Spawn UI elements with [`node_bundles::ButtonBundle`], [`node_bundles::ImageBundle`], [`node_bundles::TextBundle`] and [`node_bundles::NodeBundle`]
+//! Spawn UI elements with [`node_bundles::ButtonBundle`], [`node_bundles::ImageBundle`], [`Text`](prelude::Text) and [`node_bundles::NodeBundle`]
 //! This UI is laid out with the Flexbox and CSS Grid layout models (see <https://cssreference.io/flexbox/>)
 
 pub mod measurement;
@@ -238,6 +238,8 @@ fn build_text_interop(app: &mut App) {
             )
                 .chain()
                 .in_set(UiSystem::Prepare)
+                // Text and Text2d are independent.
+                .ambiguous_with(bevy_text::detect_text_needs_rerender::<bevy_text::Text2d>)
                 // Potential conflict: `Assets<Image>`
                 // Since both systems will only ever insert new [`Image`] assets,
                 // they will never observe each other's effects.

crates/bevy_ui/src/node_bundles.rs

@@ -13,7 +13,7 @@ use bevy_transform::prelude::{GlobalTransform, Transform};
 ///
 /// Contains the [`Node`] component and other components required to make a container.
 ///
-/// See [`node_bundles`](crate::node_bundles) for more specialized bundles like [`TextBundle`].
+/// See [`node_bundles`](crate::node_bundles) for more specialized bundles like [`ImageBundle`].
 #[derive(Bundle, Clone, Debug, Default)]
 pub struct NodeBundle {
     /// Describes the logical size of the node

crates/bevy_ui/src/ui_node.rs

@@ -2520,7 +2520,7 @@ impl<'w, 's> DefaultUiCamera<'w, 's> {
 /// Marker for controlling whether Ui is rendered with or without anti-aliasing
 /// in a camera. By default, Ui is always anti-aliased.
 ///
-/// **Note:** This does not affect text anti-aliasing. For that, use the `font_smoothing` property of the [`bevy_text::Text`] component.
+/// **Note:** This does not affect text anti-aliasing. For that, use the `font_smoothing` property of the [`TextStyle`](bevy_text::TextStyle) component.
 ///
 /// ```
 /// use bevy_core_pipeline::prelude::*;

crates/bevy_ui/src/widget/text.rs

@@ -52,7 +52,7 @@ impl Default for TextNodeFlags {
 /// Adding [`Text`] to an entity will pull in required components for setting up a UI text node.
 ///
 /// The string in this component is the first 'text span' in a hierarchy of text spans that are collected into
-/// a [`TextBlock`]. See [`TextSpan`] for the component used by children of entities with [`Text`].
+/// a [`TextBlock`]. See [`TextSpan`](bevy_text::TextSpan) for the component used by children of entities with [`Text`].
 ///
 /// Note that [`Transform`] on this entity is managed automatically by the UI layout system.
 ///