Unify crate-level preludes (#15080)

# Objective

- Crate-level prelude modules, such as `bevy_ecs::prelude`, are plagued
with inconsistency! Let's fix it!

## Solution

Format all preludes based on the following rules:

1. All preludes should have brief documentation in the format of:
   > The _name_ prelude.
   >
> This includes the most common types in this crate, re-exported for
your convenience.
2. All documentation should be outer, not inner. (`///` instead of
`//!`.)
3. No prelude modules should be annotated with `#[doc(hidden)]`. (Items
within them may, though I'm not sure why this was done.)

## Testing

- I manually searched for the term `mod prelude` and updated all
occurrences by hand. 🫠

---------

Co-authored-by: Gino Valente <[email protected]>

Author: BD103

crates/bevy_animation/src/lib.rs

@@ -39,7 +39,9 @@ use serde::{Deserialize, Serialize};
 use thread_local::ThreadLocal;
 use uuid::Uuid;
 
-#[allow(missing_docs)]
+/// The animation prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_app/src/lib.rs

@@ -27,7 +27,9 @@ pub use sub_app::*;
 #[cfg(not(target_arch = "wasm32"))]
 pub use terminal_ctrl_c_handler::*;
 
-#[allow(missing_docs)]
+/// The app prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_asset/src/lib.rs

@@ -12,6 +12,9 @@ pub mod processor;
 pub mod saver;
 pub mod transformer;
 
+/// The asset prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_audio/src/lib.rs

@@ -33,7 +33,9 @@ mod audio_source;
 mod pitch;
 mod sinks;
 
-#[allow(missing_docs)]
+/// The audio prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_color/src/lib.rs

@@ -111,7 +111,9 @@ mod test_colors;
 mod testing;
 mod xyza;
 
-/// Commonly used color types and traits.
+/// The color prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     pub use crate::color::*;
     pub use crate::color_ops::*;

crates/bevy_core/src/lib.rs

@@ -16,8 +16,10 @@ use bevy_ecs::system::Resource;
 pub use name::*;
 pub use task_pool_options::*;
 
+/// The core prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
-    //! The Bevy Core Prelude.
     #[doc(hidden)]
     pub use crate::{
         FrameCountPlugin, Name, NameOrEntity, TaskPoolOptions, TaskPoolPlugin,

crates/bevy_core_pipeline/src/lib.rs

@@ -41,6 +41,9 @@ pub mod experimental {
     }
 }
 
+/// The core pipeline prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_ecs/src/lib.rs

@@ -36,7 +36,9 @@ pub mod world;
 
 pub use bevy_ptr as ptr;
 
-/// Most commonly used re-exported types.
+/// The ECS prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     #[cfg(feature = "reflect_functions")]

crates/bevy_gizmos/src/lib.rs

@@ -51,7 +51,9 @@ mod pipeline_2d;
 #[cfg(all(feature = "bevy_pbr", feature = "bevy_render"))]
 mod pipeline_3d;
 
-/// The `bevy_gizmos` prelude.
+/// The gizmos prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[cfg(feature = "bevy_render")]
     pub use crate::aabb::{AabbGizmoConfigGroup, ShowAabbGizmo};

crates/bevy_gltf/src/lib.rs

@@ -115,7 +115,9 @@ use bevy_render::{
 };
 use bevy_scene::Scene;
 
-/// The `bevy_gltf` prelude.
+/// The glTF prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{Gltf, GltfAssetLabel, GltfExtras};

crates/bevy_hierarchy/src/lib.rs

@@ -69,7 +69,9 @@ pub use valid_parent_check_plugin::*;
 mod query_extension;
 pub use query_extension::*;
 
-#[doc(hidden)]
+/// The hierarchy prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{child_builder::*, components::*, hierarchy::*, query_extension::*};

crates/bevy_input/src/lib.rs

@@ -24,7 +24,9 @@ pub mod touch;
 pub use axis::*;
 pub use button_input::*;
 
-/// Most commonly used re-exported types.
+/// The input prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_log/src/lib.rs

@@ -28,8 +28,10 @@ mod android_tracing;
 static GLOBAL: tracy_client::ProfiledAllocator<std::alloc::System> =
     tracy_client::ProfiledAllocator::new(std::alloc::System, 100);
 
+/// The log prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
-    //! The Bevy Log Prelude.
     #[doc(hidden)]
     pub use bevy_utils::tracing::{
         debug, debug_span, error, error_span, info, info_span, trace, trace_span, warn, warn_span,

crates/bevy_math/src/lib.rs

@@ -43,7 +43,9 @@ pub use rotation2d::Rot2;
 #[cfg(feature = "rand")]
 pub use sampling::{FromRng, ShapeSample};
 
-/// The `bevy_math` prelude.
+/// The math prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     #[cfg(feature = "rand")]

crates/bevy_pbr/src/lib.rs

@@ -61,6 +61,9 @@ pub use volumetric_fog::{
     FogVolume, FogVolumeBundle, VolumetricFogPlugin, VolumetricFogSettings, VolumetricLight,
 };
 
+/// The PBR prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_picking/src/backend.rs

@@ -35,7 +35,9 @@ use bevy_ecs::prelude::*;
 use bevy_math::Vec3;
 use bevy_reflect::Reflect;
 
-/// Common imports for implementing a picking backend.
+/// The picking backend prelude.
+///
+/// This includes the most common types in this module, re-exported for your convenience.
 pub mod prelude {
     pub use super::{ray::RayMap, HitData, PointerHits};
     pub use crate::{

crates/bevy_picking/src/input.rs

@@ -29,7 +29,9 @@ use crate::{
 
 use crate::PickSet;
 
-/// Common imports for `bevy_picking`.
+/// The picking input prelude.
+///
+/// This includes the most common types in this module, re-exported for your convenience.
 pub mod prelude {
     pub use crate::input::PointerInputPlugin;
 }

crates/bevy_picking/src/lib.rs

@@ -160,7 +160,9 @@ use bevy_app::prelude::*;
 use bevy_ecs::prelude::*;
 use bevy_reflect::prelude::*;
 
-/// common exports for picking interaction
+/// The picking prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_reflect/src/lib.rs

@@ -564,6 +564,9 @@ pub mod serde;
 pub mod std_traits;
 pub mod utility;
 
+/// The reflect prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     pub use crate::std_traits::*;
     #[doc(hidden)]

crates/bevy_render/src/lib.rs

@@ -38,6 +38,10 @@ mod spatial_bundle;
 pub mod storage;
 pub mod texture;
 pub mod view;
+
+/// The render prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_scene/src/lib.rs

@@ -34,7 +34,9 @@ pub use scene_filter::*;
 pub use scene_loader::*;
 pub use scene_spawner::*;
 
-#[allow(missing_docs)]
+/// The scene prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_sprite/src/lib.rs

@@ -19,6 +19,9 @@ mod texture_atlas;
 mod texture_atlas_builder;
 mod texture_slice;
 
+/// The sprite prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[allow(deprecated)]
     #[doc(hidden)]

crates/bevy_state/src/lib.rs

@@ -47,7 +47,9 @@ pub mod state_scoped;
 /// Provides definitions for the basic traits required by the state system
 pub mod reflect;
 
-/// Most commonly used re-exported types.
+/// The state prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[cfg(feature = "bevy_app")]
     #[doc(hidden)]

crates/bevy_tasks/src/lib.rs

@@ -44,7 +44,9 @@ pub use iter::ParallelIterator;
 
 pub use futures_lite;
 
-#[allow(missing_docs)]
+/// The tasks prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_text/src/lib.rs

@@ -55,7 +55,9 @@ pub use pipeline::*;
 pub use text::*;
 pub use text2d::*;
 
-/// Most commonly used re-exported types.
+/// The text prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{Font, JustifyText, Text, Text2dBundle, TextError, TextSection, TextStyle};

crates/bevy_time/src/lib.rs

@@ -23,8 +23,10 @@ pub use time::*;
 pub use timer::*;
 pub use virt::*;
 
+/// The time prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
-    //! The Bevy Time Prelude.
     #[doc(hidden)]
     pub use crate::{Fixed, Real, Time, Timer, TimerMode, Virtual};
 }

crates/bevy_transform/src/lib.rs

@@ -29,7 +29,9 @@ pub mod helper;
 #[cfg(feature = "bevy-support")]
 pub mod systems;
 
-#[doc(hidden)]
+/// The transform prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::components::*;

crates/bevy_ui/src/lib.rs

@@ -40,7 +40,9 @@ pub use ui_material::*;
 pub use ui_node::*;
 use widget::UiImageSize;
 
-#[doc(hidden)]
+/// The UI prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_utils/src/lib.rs

@@ -10,7 +10,9 @@
 //! [Bevy]: https://bevyengine.org/
 //!
 
-#[allow(missing_docs)]
+/// The utilities prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     pub use crate::default;
 }

crates/bevy_window/src/lib.rs

@@ -30,7 +30,9 @@ pub use system::*;
 pub use system_cursor::*;
 pub use window::*;
 
-#[allow(missing_docs)]
+/// The windowing prelude.
+///
+/// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
     #[allow(deprecated)]
     #[doc(hidden)]