Partially document bevy_ui (#3526)

# Objective

Updated the docs for bevy_ui as requested by #3492 

## Solution

I have documented the parts I understand. anchors.rs is not in use and should be removed, thus I haven't documented that, and some of the more renderer-heavy code is beyond me and needs input from either cart or someone familiar with bevy rendering

Co-authored-by: Troels Jessen <[email protected]>

Author: Troels Jessen

crates/bevy_ui/src/entity.rs

@@ -1,3 +1,5 @@
+//! This module contains the bundles used in Bevy's UI
+
 use crate::{
     widget::{Button, ImageMode},
     CalculatedSize, FocusPolicy, Interaction, Node, Style, UiColor, UiImage, CAMERA_UI,
@@ -10,39 +12,66 @@ use bevy_render::{
 use bevy_text::Text;
 use bevy_transform::prelude::{GlobalTransform, Transform};
 
+/// The basic UI node
 #[derive(Bundle, Clone, Debug, Default)]
 pub struct NodeBundle {
+    /// Describes the size of the node
     pub node: Node,
+    /// Describes the style including flexbox settings
     pub style: Style,
+    /// Describes the color of the node
     pub color: UiColor,
+    /// Describes the image of the node
     pub image: UiImage,
+    /// The transform of the node
     pub transform: Transform,
+    /// The global transform of the node
     pub global_transform: GlobalTransform,
+    /// Describes the visibility properties of the node
     pub visibility: Visibility,
 }
 
+/// A UI node that is an image
 #[derive(Bundle, Clone, Debug, Default)]
 pub struct ImageBundle {
+    /// Describes the size of the node
     pub node: Node,
+    /// Describes the style including flexbox settings
     pub style: Style,
+    /// Configures how the image should scale
     pub image_mode: ImageMode,
+    /// The calculated size based on the given image
     pub calculated_size: CalculatedSize,
+    /// The color of the node
     pub color: UiColor,
+    /// The image of the node
     pub image: UiImage,
+    /// The transform of the node
     pub transform: Transform,
+    /// The global transform of the node
     pub global_transform: GlobalTransform,
+    /// Describes the visibility properties of the node
     pub visibility: Visibility,
 }
 
+/// A UI node that is text
 #[derive(Bundle, Clone, Debug)]
 pub struct TextBundle {
+    /// Describes the size of the node
     pub node: Node,
+    /// Describes the style including flexbox settings
     pub style: Style,
+    /// Contains the text of the node
     pub text: Text,
+    /// The calculated size based on the given image
     pub calculated_size: CalculatedSize,
+    /// Whether this node should block interaction with lower nodes
     pub focus_policy: FocusPolicy,
+    /// The transform of the node
     pub transform: Transform,
+    /// The global transform of the node
     pub global_transform: GlobalTransform,
+    /// Describes the visibility properties of the node
     pub visibility: Visibility,
 }
 
@@ -61,17 +90,28 @@ impl Default for TextBundle {
     }
 }
 
+/// A UI node that is a button
 #[derive(Bundle, Clone, Debug)]
 pub struct ButtonBundle {
+    /// Describes the size of the node
     pub node: Node,
+    /// Marker component that signals this node is a button
     pub button: Button,
+    /// Describes the style including flexbox settings
     pub style: Style,
+    /// Describes whether and how the button has been interacted with by the input
     pub interaction: Interaction,
+    /// Whether this node should block interaction with lower nodes
     pub focus_policy: FocusPolicy,
+    /// The color of the node
     pub color: UiColor,
+    /// The image of the node
     pub image: UiImage,
+    /// The transform of the node
     pub transform: Transform,
+    /// The global transform of the node
     pub global_transform: GlobalTransform,
+    /// Describes the visibility properties of the node
     pub visibility: Visibility,
 }
 
@@ -92,12 +132,18 @@ impl Default for ButtonBundle {
     }
 }
 
+/// The camera that is needed to see UI elements
 #[derive(Bundle, Debug)]
 pub struct UiCameraBundle {
+    /// The camera component
     pub camera: Camera,
+    /// The orthographic projection settings
     pub orthographic_projection: OrthographicProjection,
+    /// The transform of the camera
     pub transform: Transform,
+    /// The global transform of the camera
     pub global_transform: GlobalTransform,
+    /// Contains visible entities
     // FIXME there is no frustrum culling for UI
     pub visible_entities: VisibleEntities,
 }

crates/bevy_ui/src/focus.rs

@@ -14,11 +14,17 @@ use bevy_window::Windows;
 use serde::{Deserialize, Serialize};
 use smallvec::SmallVec;
 
+/// Describes what type of input interaction has occurred for a UI node.
+///
+/// This is commonly queried with a `Changed<Interaction>` filter.
 #[derive(Component, Copy, Clone, Eq, PartialEq, Debug, Reflect, Serialize, Deserialize)]
 #[reflect_value(Component, Serialize, Deserialize, PartialEq)]
 pub enum Interaction {
+    /// The node has been clicked
     Clicked,
+    /// The node has been hovered over
     Hovered,
+    /// Nothing has happened
     None,
 }
 
@@ -28,10 +34,13 @@ impl Default for Interaction {
     }
 }
 
+/// Describes whether the node should block interactions with lower nodes
 #[derive(Component, Copy, Clone, Eq, PartialEq, Debug, Reflect, Serialize, Deserialize)]
 #[reflect_value(Component, Serialize, Deserialize, PartialEq)]
 pub enum FocusPolicy {
+    /// Blocks interaction
     Block,
+    /// Lets interaction pass through
     Pass,
 }
 
@@ -41,11 +50,13 @@ impl Default for FocusPolicy {
     }
 }
 
+/// Contains entities whose Interaction should be set to None
 #[derive(Default)]
 pub struct State {
     entities_to_reset: SmallVec<[Entity; 1]>,
 }
 
+/// The system that sets Interaction for all UI elements based on the mouse cursor activity
 #[allow(clippy::type_complexity)]
 pub fn ui_focus_system(
     mut state: Local<State>,

crates/bevy_ui/src/lib.rs

@@ -1,3 +1,7 @@
+//! This crate contains Bevy's UI system, which can be used to create UI for both 2D and 3D games
+//! # Basic usage
+//! Spawn [`entity::UiCameraBundle`] and spawn UI elements with [`entity::ButtonBundle`], [`entity::ImageBundle`], [`entity::TextBundle`] and [`entity::NodeBundle`]
+//! This UI is laid out with the Flexbox paradigm (see <https://cssreference.io/flexbox/> ) except the vertical axis is inverted
 mod flex;
 mod focus;
 mod margins;
@@ -14,6 +18,7 @@ pub use margins::*;
 pub use render::*;
 pub use ui_node::*;
 
+#[doc(hidden)]
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{entity::*, ui_node::*, widget::Button, Interaction, Margins};
@@ -26,13 +31,16 @@ use bevy_math::{Rect, Size};
 use bevy_transform::TransformSystem;
 use update::{ui_z_system, update_clipping_system};
 
+/// The basic plugin for Bevy UI
 #[derive(Default)]
 pub struct UiPlugin;
 
+/// The label enum labeling the types of systems in the Bevy UI
 #[derive(Debug, Hash, PartialEq, Eq, Clone, SystemLabel)]
 pub enum UiSystem {
     /// After this label, the ui flex state has been updated
     Flex,
+    /// After this label, input interactions with UI entities have been updated for this frame
     Focus,
 }
 

crates/bevy_ui/src/margins.rs

@@ -1,12 +1,18 @@
+/// Defines the margins of a UI node
 #[derive(Debug, Clone)]
 pub struct Margins {
+    /// Left margin size in pixels
     pub left: f32,
+    /// Right margin size in pixels
     pub right: f32,
+    /// Bottom margin size in pixels
     pub bottom: f32,
+    /// Top margin size in pixels
     pub top: f32,
 }
 
 impl Margins {
+    /// Creates a new Margins based on the input
     pub fn new(left: f32, right: f32, bottom: f32, top: f32) -> Self {
         Margins {
             left,

crates/bevy_ui/src/render/camera.rs

@@ -1,8 +1,10 @@
 use bevy_ecs::prelude::*;
 use bevy_render::{camera::ActiveCameras, render_phase::RenderPhase};
 
+/// The name of the UI camera
 pub const CAMERA_UI: &str = "camera_ui";
 
+/// Inserts the [`RenderPhase`] into the UI camera
 pub fn extract_ui_camera_phases(mut commands: Commands, active_cameras: Res<ActiveCameras>) {
     if let Some(camera_ui) = active_cameras.get(CAMERA_UI) {
         if let Some(entity) = camera_ui.entity {