Very minor doc formatting changes (#5287)

# Objective

- Added a bunch of backticks to things that should have them, like equations, abstract variable names,
- Changed all small x, y, and z to capitals X, Y, Z.

This might be more annoying than helpful; Feel free to refuse this PR.

crates/bevy_core_pipeline/src/core_2d/camera_2d.rs

@@ -45,7 +45,7 @@ impl Default for Camera2dBundle {
 }
 
 impl Camera2dBundle {
-    /// Create an orthographic projection camera with a custom Z position.
+    /// Create an orthographic projection camera with a custom `Z` position.
     ///
     /// The camera is placed at `Z=far-0.1`, looking toward the world origin `(0,0,0)`.
     /// Its orthographic projection extends from `0.0` to `-far` in camera view space,

crates/bevy_ecs/src/query/fetch.rs

@@ -793,7 +793,7 @@ impl<'w, T: Component> WorldQueryGats<'w> for &mut T {
     type _State = ComponentIdState<T>;
 }
 
-/// SAFETY: component access and archetype component access are properly updated to reflect that T is
+/// SAFETY: component access and archetype component access are properly updated to reflect that `T` is
 /// read and write
 unsafe impl<'w, T: Component> Fetch<'w> for WriteFetch<'w, T> {
     type Item = Mut<'w, T>;

crates/bevy_ecs/src/query/state.rs

@@ -515,10 +515,10 @@ impl<Q: WorldQuery, F: WorldQuery> QueryState<Q, F> {
     /// Returns an [`Iterator`] over all possible combinations of `K` query results without repetition.
     /// This can only be called for read-only queries.
     ///
-    ///  For permutations of size K of query returning N results, you will get:
-    /// - if K == N: one permutation of all query results
-    /// - if K < N: all possible K-sized combinations of query results, without repetition
-    /// - if K > N: empty set (no K-sized combinations exist)
+    ///  For permutations of size `K` of query returning `N` results, you will get:
+    /// - if `K == N`: one permutation of all query results
+    /// - if `K < N`: all possible `K`-sized combinations of query results, without repetition
+    /// - if `K > N`: empty set (no `K`-sized combinations exist)
     ///
     /// This can only be called for read-only queries, see [`Self::iter_combinations_mut`] for
     /// write-queries.
@@ -541,10 +541,10 @@ impl<Q: WorldQuery, F: WorldQuery> QueryState<Q, F> {
     /// Iterates over all possible combinations of `K` query results for the given [`World`]
     /// without repetition.
     ///
-    ///  For permutations of size K of query returning N results, you will get:
-    /// - if K == N: one permutation of all query results
-    /// - if K < N: all possible K-sized combinations of query results, without repetition
-    /// - if K > N: empty set (no K-sized combinations exist)
+    ///  For permutations of size `K` of query returning `N` results, you will get:
+    /// - if `K == N`: one permutation of all query results
+    /// - if `K < N`: all possible `K`-sized combinations of query results, without repetition
+    /// - if `K > N`: empty set (no `K`-sized combinations exist)
     #[inline]
     pub fn iter_combinations_mut<'w, 's, const K: usize>(
         &'s mut self,

crates/bevy_ecs/src/system/function_system.rs

@@ -508,7 +508,7 @@ impl<T> SystemLabel for SystemTypeIdLabel<T> {
 ///
 /// // Unfortunately, we need all of these generics. `A` is the first system, with its
 /// // parameters and marker type required for coherence. `B` is the second system, and
-/// // the other generics are for the input/output types of A and B.
+/// // the other generics are for the input/output types of `A` and `B`.
 /// /// Chain creates a new system which calls `a`, then calls `b` with the output of `a`
 /// pub fn chain<AIn, Shared, BOut, A, AParam, AMarker, B, BParam, BMarker>(
 ///     mut a: A,

crates/bevy_ecs/src/system/query.rs

@@ -334,10 +334,10 @@ impl<'w, 's, Q: WorldQuery, F: WorldQuery> Query<'w, 's, Q, F> {
     /// Returns an [`Iterator`] over all possible combinations of `K` query results without repetition.
     /// This can only return immutable data
     ///
-    ///  For permutations of size K of query returning N results, you will get:
-    /// - if K == N: one permutation of all query results
-    /// - if K < N: all possible K-sized combinations of query results, without repetition
-    /// - if K > N: empty set (no K-sized combinations exist)
+    ///  For permutations of size `K` of query returning `N` results, you will get:
+    /// - if `K == N`: one permutation of all query results
+    /// - if `K < N`: all possible `K`-sized combinations of query results, without repetition
+    /// - if `K > N`: empty set (no `K`-sized combinations exist)
     #[inline]
     pub fn iter_combinations<const K: usize>(&self) -> QueryCombinationIter<'_, '_, Q, F, K> {
         // SAFETY: system runs without conflicts with other systems.

crates/bevy_ecs/src/system/system_chaining.rs

@@ -10,8 +10,8 @@ use std::borrow::Cow;
 /// A [`System`] that chains two systems together, creating a new system that routes the output of
 /// the first system into the input of the second system, yielding the output of the second system.
 ///
-/// Given two systems A and B, A may be chained with B as `A.chain(B)` if the output type of A is
-/// equal to the input type of B.
+/// Given two systems `A` and `B`, A may be chained with `B` as `A.chain(B)` if the output type of `A` is
+/// equal to the input type of `B`.
 ///
 /// Note that for [`FunctionSystem`](crate::system::FunctionSystem)s the output is the return value
 /// of the function and the input is the first [`SystemParam`](crate::system::SystemParam) if it is

crates/bevy_pbr/src/light.rs

@@ -280,9 +280,9 @@ pub enum ClusterFarZMode {
 /// Configure the depth-slicing strategy for clustered forward rendering
 #[derive(Debug, Copy, Clone)]
 pub struct ClusterZConfig {
-    /// Far z plane of the first depth slice
+    /// Far `Z` plane of the first depth slice
     pub first_slice_depth: f32,
-    /// Strategy for how to evaluate the far z plane of the furthest depth slice
+    /// Strategy for how to evaluate the far `Z` plane of the furthest depth slice
     pub far_z_mode: ClusterFarZMode,
 }
 
@@ -303,24 +303,24 @@ pub enum ClusterConfig {
     /// One single cluster. Optimal for low-light complexity scenes or scenes where
     /// most lights affect the entire scene.
     Single,
-    /// Explicit x, y and z counts (may yield non-square x/y clusters depending on the aspect ratio)
+    /// Explicit `X`, `Y` and `Z` counts (may yield non-square `X/Y` clusters depending on the aspect ratio)
     XYZ {
         dimensions: UVec3,
         z_config: ClusterZConfig,
-        /// Specify if clusters should automatically resize in x/y if there is a risk of exceeding
+        /// Specify if clusters should automatically resize in `X/Y` if there is a risk of exceeding
         /// the available cluster-light index limit
         dynamic_resizing: bool,
     },
-    /// Fixed number of z slices, x and y calculated to give square clusters
+    /// Fixed number of `Z` slices, `X` and `Y` calculated to give square clusters
     /// with at most total clusters. For top-down games where lights will generally always be within a
-    /// short depth range, it may be useful to use this configuration with 1 or few z slices. This
+    /// short depth range, it may be useful to use this configuration with 1 or few `Z` slices. This
     /// would reduce the number of lights per cluster by distributing more clusters in screen space
-    /// x/y which matches how lights are distributed in the scene.
+    /// `X/Y` which matches how lights are distributed in the scene.
     FixedZ {
         total: u32,
         z_slices: u32,
         z_config: ClusterZConfig,
-        /// Specify if clusters should automatically resize in x/y if there is a risk of exceeding
+        /// Specify if clusters should automatically resize in `X/Y` if there is a risk of exceeding
         /// the available cluster-light index limit
         dynamic_resizing: bool,
     },
@@ -329,7 +329,7 @@ pub enum ClusterConfig {
 impl Default for ClusterConfig {
     fn default() -> Self {
         // 24 depth slices, square clusters with at most 4096 total clusters
-        // use max light distance as clusters max Z-depth, first slice extends to 5.0
+        // use max light distance as clusters max `Z`-depth, first slice extends to 5.0
         Self::FixedZ {
             total: 4096,
             z_slices: 24,
@@ -412,7 +412,7 @@ impl ClusterConfig {
 pub struct Clusters {
     /// Tile size
     pub(crate) tile_size: UVec2,
-    /// Number of clusters in x / y / z in the view frustum
+    /// Number of clusters in `X` / `Y` / `Z` in the view frustum
     pub(crate) dimensions: UVec3,
     /// Distance to the far plane of the first depth slice. The first depth slice is special
     /// and explicitly-configured to avoid having unnecessarily many slices close to the camera.
@@ -555,10 +555,10 @@ fn ndc_position_to_cluster(
 const VEC2_HALF: Vec2 = Vec2::splat(0.5);
 const VEC2_HALF_NEGATIVE_Y: Vec2 = Vec2::new(0.5, -0.5);
 
-// Calculate bounds for the light using a view space aabb.
-// Returns a (Vec3, Vec3) containing min and max with
-//     x and y in normalized device coordinates with range [-1, 1]
-//     z in view space, with range [-inf, -f32::MIN_POSITIVE]
+/// Calculate bounds for the light using a view space aabb.
+/// Returns a `(Vec3, Vec3)` containing minimum and maximum with
+///     `X` and `Y` in normalized device coordinates with range `[-1, 1]`
+///     `Z` in view space, with range `[-inf, -f32::MIN_POSITIVE]`
 fn cluster_space_light_aabb(
     inverse_view_transform: Mat4,
     projection_matrix: Mat4,

crates/bevy_pbr/src/render/light.rs

@@ -378,7 +378,7 @@ pub struct ExtractedClusterConfig {
     /// Special near value for cluster calculations
     near: f32,
     far: f32,
-    /// Number of clusters in x / y / z in the view frustum
+    /// Number of clusters in `X` / `Y` / `Z` in the view frustum
     dimensions: UVec3,
 }
 

crates/bevy_render/src/camera/camera.rs

@@ -314,7 +314,7 @@ pub enum DepthCalculation {
     /// Pythagorean distance; works everywhere, more expensive to compute.
     #[default]
     Distance,
-    /// Optimization for 2D; assuming the camera points towards -Z.
+    /// Optimization for 2D; assuming the camera points towards `-Z`.
     ZDifference,
 }
 

crates/bevy_render/src/color/mod.rs

@@ -527,10 +527,10 @@ impl Color {
         }
     }
 
-    /// Converts Color to a u32 from sRGB colorspace.
+    /// Converts `Color` to a `u32` from sRGB colorspace.
     ///
     /// Maps the RGBA channels in RGBA order to a little-endian byte array (GPUs are little-endian).
-    /// A will be the most significant byte and R the least significant.
+    /// `A` will be the most significant byte and `R` the least significant.
     pub fn as_rgba_u32(self: Color) -> u32 {
         match self {
             Color::Rgba {
@@ -576,7 +576,7 @@ impl Color {
     /// Converts Color to a u32 from linear RGB colorspace.
     ///
     /// Maps the RGBA channels in RGBA order to a little-endian byte array (GPUs are little-endian).
-    /// A will be the most significant byte and R the least significant.
+    /// `A` will be the most significant byte and `R` the least significant.
     pub fn as_linear_rgba_u32(self: Color) -> u32 {
         match self {
             Color::Rgba {

crates/bevy_render/src/mesh/shape/capsule.rs

@@ -5,11 +5,11 @@ use wgpu::PrimitiveTopology;
 /// A cylinder with hemispheres at the top and bottom
 #[derive(Debug, Copy, Clone)]
 pub struct Capsule {
-    /// Radius on the xz plane.
+    /// Radius on the `XZ` plane.
     pub radius: f32,
     /// Number of sections in cylinder between hemispheres.
     pub rings: usize,
-    /// Height of the middle cylinder on the y axis, excluding the hemispheres.
+    /// Height of the middle cylinder on the `Y` axis, excluding the hemispheres.
     pub depth: f32,
     /// Number of latitudes, distributed by inclination. Must be even.
     pub latitudes: usize,

crates/bevy_render/src/mesh/shape/mod.rs

@@ -114,7 +114,7 @@ impl From<Box> for Mesh {
     }
 }
 
-/// A rectangle on the XY plane centered at the origin.
+/// A rectangle on the `XY` plane centered at the origin.
 #[derive(Debug, Copy, Clone)]
 pub struct Quad {
     /// Full width and height of the rectangle.
@@ -167,7 +167,7 @@ impl From<Quad> for Mesh {
     }
 }
 
-/// A square on the XZ plane centered at the origin.
+/// A square on the `XZ` plane centered at the origin.
 #[derive(Debug, Copy, Clone)]
 pub struct Plane {
     /// The total side length of the square.

crates/bevy_render/src/mesh/shape/regular_polygon.rs

@@ -1,10 +1,10 @@
 use crate::mesh::{Indices, Mesh};
 use wgpu::PrimitiveTopology;
 
-/// A regular polygon in the xy plane
+/// A regular polygon in the `XY` plane
 #[derive(Debug, Copy, Clone)]
 pub struct RegularPolygon {
-    /// Inscribed radius in the xy plane.
+    /// Inscribed radius in the `XY` plane.
     pub radius: f32,
     /// Number of sides.
     pub sides: usize,
@@ -20,7 +20,7 @@ impl Default for RegularPolygon {
 }
 
 impl RegularPolygon {
-    /// Creates a regular polygon in the xy plane
+    /// Creates a regular polygon in the `XY` plane
     pub fn new(radius: f32, sides: usize) -> Self {
         Self { radius, sides }
     }
@@ -60,9 +60,9 @@ impl From<RegularPolygon> for Mesh {
     }
 }
 
-/// A circle in the xy plane
+/// A circle in the `XY` plane
 pub struct Circle {
-    /// Inscribed radius in the xy plane.
+    /// Inscribed radius in the `XY` plane.
     pub radius: f32,
     /// The number of vertices used.
     pub vertices: usize,
@@ -78,7 +78,7 @@ impl Default for Circle {
 }
 
 impl Circle {
-    /// Creates a circle in the xy plane
+    /// Creates a circle in the `XY` plane
     pub fn new(radius: f32) -> Self {
         Self {
             radius,

crates/bevy_render/src/primitives/mod.rs

@@ -81,8 +81,8 @@ impl Sphere {
 }
 
 /// A plane defined by a unit normal and distance from the origin along the normal
-/// Any point p is in the plane if n.p + d = 0
-/// For planes defining half-spaces such as for frusta, if n.p + d > 0 then p is on
+/// Any point `p` is in the plane if `n.p + d = 0`
+/// For planes defining half-spaces such as for frusta, if `n.p + d > 0` then `p` is on
 /// the positive side (inside) of the plane.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct Plane {

crates/bevy_render/src/rangefinder.rs

@@ -14,7 +14,7 @@ impl ViewRangefinder3d {
         }
     }
 
-    /// Calculates the distance, or view-space Z value, for a transform
+    /// Calculates the distance, or view-space `Z` value, for a transform
     #[inline]
     pub fn distance(&self, transform: &Mat4) -> f32 {
         // NOTE: row 2 of the inverse view matrix dotted with column 3 of the model matrix

crates/bevy_sprite/src/sprite.rs

@@ -8,9 +8,9 @@ use bevy_render::color::Color;
 pub struct Sprite {
     /// The sprite's color tint
     pub color: Color,
-    /// Flip the sprite along the X axis
+    /// Flip the sprite along the `X` axis
     pub flip_x: bool,
-    /// Flip the sprite along the Y axis
+    /// Flip the sprite along the `Y` axis
     pub flip_y: bool,
     /// An optional custom size for the sprite that will be used when rendering, instead of the size
     /// of the sprite's image

crates/bevy_tasks/src/task_pool.rs

@@ -14,8 +14,8 @@ use crate::Task;
 #[derive(Debug, Default, Clone)]
 #[must_use]
 pub struct TaskPoolBuilder {
-    /// If set, we'll set up the thread pool to use at most n threads. Otherwise use
-    /// the logical core count of the system
+    /// If set, we'll set up the thread pool to use at most `num_threads` threads.
+    /// Otherwise use the logical core count of the system
     num_threads: Option<usize>,
     /// If set, we'll use the given stack size rather than the system default
     stack_size: Option<usize>,

crates/bevy_transform/src/components/global_transform.rs

@@ -138,7 +138,7 @@ impl GlobalTransform {
         Affine3A::from_scale_rotation_translation(self.scale, self.rotation, self.translation)
     }
 
-    /// Get the unit vector in the local x direction
+    /// Get the unit vector in the local `X` direction
     #[inline]
     pub fn local_x(&self) -> Vec3 {
         self.rotation * Vec3::X
@@ -156,7 +156,7 @@ impl GlobalTransform {
         self.local_x()
     }
 
-    /// Get the unit vector in the local y direction
+    /// Get the unit vector in the local `Y` direction
     #[inline]
     pub fn local_y(&self) -> Vec3 {
         self.rotation * Vec3::Y
@@ -174,7 +174,7 @@ impl GlobalTransform {
         -self.local_y()
     }
 
-    /// Get the unit vector in the local z direction
+    /// Get the unit vector in the local `Z` direction
     #[inline]
     pub fn local_z(&self) -> Vec3 {
         self.rotation * Vec3::Z

crates/bevy_transform/src/components/transform.rs

@@ -101,7 +101,7 @@ impl Transform {
     }
 
     /// Updates and returns this [`Transform`] by rotating it so that its unit vector in the
-    /// local z direction is toward `target` and its unit vector in the local y direction
+    /// local `Z` direction is toward `target` and its unit vector in the local `Y` direction
     /// is toward `up`.
     #[inline]
     #[must_use]
@@ -141,7 +141,7 @@ impl Transform {
         Mat4::from_scale_rotation_translation(self.scale, self.rotation, self.translation)
     }
 
-    /// Get the unit vector in the local x direction.
+    /// Get the unit vector in the local `X` direction.
     #[inline]
     pub fn local_x(&self) -> Vec3 {
         self.rotation * Vec3::X
@@ -159,7 +159,7 @@ impl Transform {
         self.local_x()
     }
 
-    /// Get the unit vector in the local y direction.
+    /// Get the unit vector in the local `Y` direction.
     #[inline]
     pub fn local_y(&self) -> Vec3 {
         self.rotation * Vec3::Y
@@ -177,7 +177,7 @@ impl Transform {
         -self.local_y()
     }
 
-    /// Get the unit vector in the local z direction.
+    /// Get the unit vector in the local `Z` direction.
     #[inline]
     pub fn local_z(&self) -> Vec3 {
         self.rotation * Vec3::Z
@@ -209,7 +209,7 @@ impl Transform {
         self.rotate(Quat::from_axis_angle(axis, angle));
     }
 
-    /// Rotates this [`Transform`] around the X axis by `angle` (in radians).
+    /// Rotates this [`Transform`] around the `X` axis by `angle` (in radians).
     ///
     /// If this [`Transform`] has a parent, the axis is relative to the rotation of the parent.
     #[inline]
@@ -217,7 +217,7 @@ impl Transform {
         self.rotate(Quat::from_rotation_x(angle));
     }
 
-    /// Rotates this [`Transform`] around the Y axis by `angle` (in radians).
+    /// Rotates this [`Transform`] around the `Y` axis by `angle` (in radians).
     ///
     /// If this [`Transform`] has a parent, the axis is relative to the rotation of the parent.
     #[inline]
@@ -225,7 +225,7 @@ impl Transform {
         self.rotate(Quat::from_rotation_y(angle));
     }
 
-    /// Rotates this [`Transform`] around the Z axis by `angle` (in radians).
+    /// Rotates this [`Transform`] around the `Z` axis by `angle` (in radians).
     ///
     /// If this [`Transform`] has a parent, the axis is relative to the rotation of the parent.
     #[inline]
@@ -233,19 +233,19 @@ impl Transform {
         self.rotate(Quat::from_rotation_z(angle));
     }
 
-    /// Rotates this [`Transform`] around its X axis by `angle` (in radians).
+    /// Rotates this [`Transform`] around its `X` axis by `angle` (in radians).
     #[inline]
     pub fn rotate_local_x(&mut self, angle: f32) {
         self.rotate_axis(self.local_x(), angle);
     }
 
-    /// Rotates this [`Transform`] around its Y axis by `angle` (in radians).
+    /// Rotates this [`Transform`] around its `Y` axis by `angle` (in radians).
     #[inline]
     pub fn rotate_local_y(&mut self, angle: f32) {
         self.rotate_axis(self.local_y(), angle);
     }
 
-    /// Rotates this [`Transform`] around its Z axis by `angle` (in radians).
+    /// Rotates this [`Transform`] around its `Z` axis by `angle` (in radians).
     #[inline]
     pub fn rotate_local_z(&mut self, angle: f32) {
         self.rotate_axis(self.local_z(), angle);
@@ -260,8 +260,8 @@ impl Transform {
         self.rotation *= rotation;
     }
 
-    /// Rotates this [`Transform`] so that its local negative z direction is toward
-    /// `target` and its local y direction is toward `up`.
+    /// Rotates this [`Transform`] so that its local negative `Z` direction is toward
+    /// `target` and its local `Y` direction is toward `up`.
     #[inline]
     pub fn look_at(&mut self, target: Vec3, up: Vec3) {
         let forward = Vec3::normalize(self.translation - target);

crates/bevy_ui/src/update.rs

@@ -13,10 +13,10 @@ use bevy_math::Vec2;
 use bevy_sprite::Rect;
 use bevy_transform::components::{GlobalTransform, Transform};
 
-/// The resolution of Z values for UI
+/// The resolution of `Z` values for UI
 pub const UI_Z_STEP: f32 = 0.001;
 
-/// Updates transforms of nodes to fit with the z system
+/// Updates transforms of nodes to fit with the `Z` system
 pub fn ui_z_system(
     root_node_query: Query<Entity, (With<Node>, Without<Parent>)>,
     mut node_query: Query<&mut Transform, With<Node>>,

examples/2d/rotation.rs

@@ -44,9 +44,9 @@ struct RotateToPlayer {
 ///
 /// The Bevy coordinate system is the same for 2D and 3D, in terms of 2D this means that:
 ///
-/// * X axis goes from left to right (+X points right)
-/// * Y axis goes from bottom to top (+Y point up)
-/// * Z axis goes from far to near (+Z points towards you, out of the screen)
+/// * `X` axis goes from left to right (`+X` points right)
+/// * `Y` axis goes from bottom to top (`+Y` point up)
+/// * `Z` axis goes from far to near (`+Z` points towards you, out of the screen)
 ///
 /// The origin is at the center of the screen.
 fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {

examples/input/keyboard_modifiers.rs

@@ -12,7 +12,7 @@ fn main() {
         .run();
 }
 
-/// This system prints when Ctrl + Shift + A is pressed
+/// This system prints when `Ctrl + Shift + A` is pressed
 fn keyboard_input_system(input: Res<Input<KeyCode>>) {
     let shift = input.any_pressed([KeyCode::LShift, KeyCode::RShift]);
     let ctrl = input.any_pressed([KeyCode::LControl, KeyCode::RControl]);