Repository: bevyengine/bevy
File: crates/bevy_text/src/text.rs (Rust)

Code before:
        Self::default().with_no_wrap()
    }

    /// Returns this [`TextLayout`] with the specified [`Justify`].
    pub const fn with_justify(mut self, justify: Justify) -> Self {
        self.justify = justify;
        self
    }

    /// Returns this [`TextLayout`] with the specified [`LineBreak`].
    pub const fn with_linebreak(mut self, linebreak: LineBreak) -> Self {
        self.linebreak = linebreak;
        self
    }

    /// Returns this [`TextLayout`] with soft wrapping disabled.
    /// Hard wrapping, where text contains an explicit linebreak such as the escape sequence `\n`, will still occur.
    pub const fn with_no_wrap(mut self) -> Self {
        self.linebreak = LineBreak::NoWrap;
        self
    }
}

/// A span of text in a tree of spans.
///
/// `TextSpan` is only valid as a child of an entity with `Text` or `Text2d` which is the first span.
/// Spans are collected in hierarchy traversal order into a [`ComputedTextBlock`] for layout.
/// [`TextLayout`] of the first span determines the layout of the entire block. Each node has its own
/// [`TextFont`] and [`TextColor`].
///
/// ```
/// # use bevy_asset::Handle;
/// # use bevy_color::Color;
/// # use bevy_color::palettes::basic::{BLUE, GREEN, RED};
/// # use bevy_ecs::{children, spawn::SpawnRelated, world::World};
/// # use bevy_text::{Font, Justify, Text2d, TextColor, TextLayout, TextFont, TextSpan};
///
/// # let font_handle: Handle<Font> = Default::default();
/// # let mut world = World::default();
/// #
/// world.spawn((
///     // `Text` or `Text2d` is needed.
///     Text2d::new("Bevy\n"),
///     // Layout of the entire block of text.
///     TextLayout::new_with_justify(Justify::Center),
///     // TextFont of this node. Won't apply to children.
///     TextFont::from_font_size(50.0),
///     // TextColor of this node. Won't apply to children.
///     TextColor(BLUE.into()),
///     children![
///         // Children must be `TextSpan`, not `Text` or `Text2d`.

Review comment (suggestion):
Unfortunately, it's hard to clearly convey this thought without ambiguities. How about something like:

---

A `TextSpan` is only valid when it exists as a child entity of a parent that has either a `Text` or `Text2d` component.

The parent entity's `Text`/`Text2d` component contains the base text content. Any child entities with `TextSpan` components extend this text by appending their content to the parent's text in sequence.

Code after:
        Self::default().with_no_wrap()
    }

    /// Returns this [`TextLayout`] with the specified [`Justify`].
    pub const fn with_justify(mut self, justify: Justify) -> Self {
        self.justify = justify;
        self
    }

    /// Returns this [`TextLayout`] with the specified [`LineBreak`].
    pub const fn with_linebreak(mut self, linebreak: LineBreak) -> Self {
        self.linebreak = linebreak;
        self
    }

    /// Returns this [`TextLayout`] with soft wrapping disabled.
    /// Hard wrapping, where text contains an explicit linebreak such as the escape sequence `\n`, will still occur.
    pub const fn with_no_wrap(mut self) -> Self {
        self.linebreak = LineBreak::NoWrap;
        self
    }
}

/// A span of text in a tree of spans.
///
/// A `TextSpan` is only valid when it exists as a child of a parent that has either `Text` or
/// `Text2d`. The parent's `Text` / `Text2d` component contains the base text content. Any children
/// with `TextSpan` extend this text by appending their content to the parent's text in sequence to
/// form a [`ComputedTextBlock`]. The parent's [`TextLayout`] determines the layout of the block
/// but each node has its own [`TextFont`] and [`TextColor`].
///
/// ```
/// # use bevy_asset::Handle;
/// # use bevy_color::Color;
/// # use bevy_color::palettes::basic::{BLUE, GREEN, RED};
/// # use bevy_ecs::{children, spawn::SpawnRelated, world::World};
/// # use bevy_text::{Font, Justify, Text2d, TextColor, TextLayout, TextFont, TextSpan};
///
/// # let font_handle: Handle<Font> = Default::default();
/// # let mut world = World::default();
/// #
/// world.spawn((
///     // `Text` or `Text2d` is needed.
///     Text2d::new("Bevy\n"),
///     // Layout of the entire block of text.
///     TextLayout::new_with_justify(Justify::Center),
///     // TextFont of this node. Won't apply to children.
///     TextFont::from_font_size(50.0),
///     // TextColor of this node. Won't apply to children.
///     TextColor(BLUE.into()),
///     // Children must be `TextSpan`, not `Text` or `Text2d`.