Add some more docs for bevy_text. (#9873)

# Objective

- Have more docs for `bevy_text` to avoid reading the source code for
some things.

## Solution

- Add some additional docs.

## Changelog

- `TextSettings.max_font_atlases` in `bevy_text` has been renamed to `
TextSettings.soft_max_font_atlases`.

## Migration Guide

- Usages of `TextSettings.max_font_atlases` from `bevy_text` must be
changed to `TextSettings.soft_max_font_atlases`.

crates/bevy_text/src/glyph_brush.rs

@@ -115,9 +115,9 @@ impl GlyphBrush {
 
                 if !text_settings.allow_dynamic_font_size
                     && !font_atlas_warning.warned
-                    && font_atlas_set.len() > text_settings.max_font_atlases.get()
+                    && font_atlas_set.len() > text_settings.soft_max_font_atlases.get()
                 {
-                    warn!("warning[B0005]: Number of font atlases has exceeded the maximum of {}. Performance and memory usage may suffer.", text_settings.max_font_atlases.get());
+                    warn!("warning[B0005]: Number of font atlases has exceeded the maximum of {}. Performance and memory usage may suffer.", text_settings.soft_max_font_atlases.get());
                     font_atlas_warning.warned = true;
                 }
 

crates/bevy_text/src/lib.rs

@@ -34,15 +34,21 @@ use bevy_render::{camera::CameraUpdateSystem, ExtractSchedule, RenderApp};
 use bevy_sprite::SpriteSystem;
 use std::num::NonZeroUsize;
 
+/// Adds text rendering support to an app.
+///
+/// When the `bevy_text` feature is enabled with the `bevy` crate, this
+/// plugin is included by default in the `DefaultPlugins`.
 #[derive(Default)]
 pub struct TextPlugin;
 
-/// [`TextPlugin`] settings
+/// Settings used to configure the [`TextPlugin`].
 #[derive(Resource)]
 pub struct TextSettings {
-    /// Maximum number of font atlases supported in a [`FontAtlasSet`].
+    /// Soft maximum number of font atlases supported in a [`FontAtlasSet`]. When this is exceeded,
-    pub max_font_atlases: NonZeroUsize,
+    /// a warning will be emitted a single time. The [`FontAtlasWarning`] resource ensures that
-    /// Allows font size to be set dynamically exceeding the amount set in `max_font_atlases`.
+    /// this only happens once.
+    pub soft_max_font_atlases: NonZeroUsize,
+    /// Allows font size to be set dynamically exceeding the amount set in `soft_max_font_atlases`.
     /// Note each font size has to be generated which can have a strong performance impact.
     pub allow_dynamic_font_size: bool,
 }
@@ -50,19 +56,21 @@ pub struct TextSettings {
 impl Default for TextSettings {
     fn default() -> Self {
         Self {
-            max_font_atlases: NonZeroUsize::new(16).unwrap(),
+            soft_max_font_atlases: NonZeroUsize::new(16).unwrap(),
             allow_dynamic_font_size: false,
         }
     }
 }
 
+/// This resource tracks whether or not a warning has been emitted due to the number
+/// of font atlases exceeding the [`TextSettings::soft_max_font_atlases`] setting.
 #[derive(Resource, Default)]
 pub struct FontAtlasWarning {
     warned: bool,
 }
 
-/// Text is rendered for two different view projections, normal `Text2DBundle` is rendered with a
+/// Text is rendered for two different view projections, a [`Text2dBundle`] is rendered with a
-/// `BottomToTop` y axis, and UI is rendered with a `TopToBottom` y axis. This matters for text because
+/// `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.
 pub enum YAxisOrientation {
     TopToBottom,

crates/bevy_text/src/text2d.rs

@@ -78,6 +78,8 @@ pub struct Text2dBundle {
     pub text_layout_info: TextLayoutInfo,
 }
 
+/// This system extracts the sprites from the 2D text components and adds them to the
+/// "render world".
 pub fn extract_text2d_sprite(
     mut commands: Commands,
     mut extracted_sprites: ResMut<ExtractedSprites>,
@@ -148,7 +150,7 @@ pub fn extract_text2d_sprite(
 }
 
 /// Updates the layout and size information whenever the text or style is changed.
-/// This information is computed by the `TextPipeline` on insertion, then stored.
+/// This information is computed by the [`TextPipeline`] on insertion, then stored.
 ///
 /// ## World Resources
 ///
@@ -222,6 +224,7 @@ pub fn update_text2d_layout(
     }
 }
 
+/// Scales `value` by `factor`.
 pub fn scale_value(value: f32, factor: f64) -> f32 {
     (value as f64 * factor) as f32
 }

errors/B0005.md

@@ -6,4 +6,4 @@ Separate font atlases are created for each font and font size. This is expensive
 
 If you need to smoothly scale font size, use `Transform::scale`.
 
-You can disable this warning by setting `TextSettings::allow_dynamic_font_size` to `true` or raise the limit by setting `TextSettings::max_font_atlases`.
+You can disable this warning by setting `TextSettings::allow_dynamic_font_size` to `true` or raise the limit by setting `TextSettings::soft_max_font_atlases`.