From 6ec6a556450c1d417df6906b2e3cb2787e2d5b4e Mon Sep 17 00:00:00 2001
From: BD103 <59022059+BD103@users.noreply.github.com>
Date: Sun, 8 Sep 2024 13:10:57 -0400
Subject: [PATCH] Unify crate-level preludes (#15080)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

# 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 <49806985+MrGVSV@users.noreply.github.com>
---
 crates/bevy_animation/src/lib.rs     | 4 +++-
 crates/bevy_app/src/lib.rs           | 4 +++-
 crates/bevy_asset/src/lib.rs         | 3 +++
 crates/bevy_audio/src/lib.rs         | 4 +++-
 crates/bevy_color/src/lib.rs         | 4 +++-
 crates/bevy_core/src/lib.rs          | 4 +++-
 crates/bevy_core_pipeline/src/lib.rs | 3 +++
 crates/bevy_ecs/src/lib.rs           | 4 +++-
 crates/bevy_gizmos/src/lib.rs        | 4 +++-
 crates/bevy_gltf/src/lib.rs          | 4 +++-
 crates/bevy_hierarchy/src/lib.rs     | 4 +++-
 crates/bevy_input/src/lib.rs         | 4 +++-
 crates/bevy_log/src/lib.rs           | 4 +++-
 crates/bevy_math/src/lib.rs          | 4 +++-
 crates/bevy_pbr/src/lib.rs           | 3 +++
 crates/bevy_picking/src/backend.rs   | 4 +++-
 crates/bevy_picking/src/input.rs     | 4 +++-
 crates/bevy_picking/src/lib.rs       | 4 +++-
 crates/bevy_reflect/src/lib.rs       | 3 +++
 crates/bevy_render/src/lib.rs        | 4 ++++
 crates/bevy_scene/src/lib.rs         | 4 +++-
 crates/bevy_sprite/src/lib.rs        | 3 +++
 crates/bevy_state/src/lib.rs         | 4 +++-
 crates/bevy_tasks/src/lib.rs         | 4 +++-
 crates/bevy_text/src/lib.rs          | 4 +++-
 crates/bevy_time/src/lib.rs          | 4 +++-
 crates/bevy_transform/src/lib.rs     | 4 +++-
 crates/bevy_ui/src/lib.rs            | 4 +++-
 crates/bevy_utils/src/lib.rs         | 4 +++-
 crates/bevy_window/src/lib.rs        | 4 +++-
 30 files changed, 91 insertions(+), 24 deletions(-)

diff --git a/crates/bevy_animation/src/lib.rs b/crates/bevy_animation/src/lib.rs
index 83dbded00d..7be1b6d88e 100755
--- a/crates/bevy_animation/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_app/src/lib.rs b/crates/bevy_app/src/lib.rs
index b389395d3d..8ea7c0e767 100644
--- a/crates/bevy_app/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_asset/src/lib.rs b/crates/bevy_asset/src/lib.rs
index d49bae9e63..f7787fb809 100644
--- a/crates/bevy_asset/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_audio/src/lib.rs b/crates/bevy_audio/src/lib.rs
index 1d5df733a0..65d7b4e6bc 100644
--- a/crates/bevy_audio/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_color/src/lib.rs b/crates/bevy_color/src/lib.rs
index c03c1dd348..344a159695 100644
--- a/crates/bevy_color/src/lib.rs
+++ b/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::*;
diff --git a/crates/bevy_core/src/lib.rs b/crates/bevy_core/src/lib.rs
index df41f46c46..94a8b3a541 100644
--- a/crates/bevy_core/src/lib.rs
+++ b/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,
diff --git a/crates/bevy_core_pipeline/src/lib.rs b/crates/bevy_core_pipeline/src/lib.rs
index 568f2cf3f1..ec77241466 100644
--- a/crates/bevy_core_pipeline/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_ecs/src/lib.rs b/crates/bevy_ecs/src/lib.rs
index 442c25d9a2..cbaf638e29 100644
--- a/crates/bevy_ecs/src/lib.rs
+++ b/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")]
diff --git a/crates/bevy_gizmos/src/lib.rs b/crates/bevy_gizmos/src/lib.rs
index 10f7e9cdc9..bbef44df46 100644
--- a/crates/bevy_gizmos/src/lib.rs
+++ b/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};
diff --git a/crates/bevy_gltf/src/lib.rs b/crates/bevy_gltf/src/lib.rs
index 722dde2150..bca24f0af7 100644
--- a/crates/bevy_gltf/src/lib.rs
+++ b/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};
diff --git a/crates/bevy_hierarchy/src/lib.rs b/crates/bevy_hierarchy/src/lib.rs
index 75fc849202..98011ced58 100755
--- a/crates/bevy_hierarchy/src/lib.rs
+++ b/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::*};
diff --git a/crates/bevy_input/src/lib.rs b/crates/bevy_input/src/lib.rs
index 83984af1e6..b4dac1ee7f 100644
--- a/crates/bevy_input/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_log/src/lib.rs b/crates/bevy_log/src/lib.rs
index b3c1991769..0cbb6b207d 100644
--- a/crates/bevy_log/src/lib.rs
+++ b/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,
diff --git a/crates/bevy_math/src/lib.rs b/crates/bevy_math/src/lib.rs
index cbbc25e219..70df008694 100644
--- a/crates/bevy_math/src/lib.rs
+++ b/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")]
diff --git a/crates/bevy_pbr/src/lib.rs b/crates/bevy_pbr/src/lib.rs
index 5deaa88590..ba2848b8a8 100644
--- a/crates/bevy_pbr/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_picking/src/backend.rs b/crates/bevy_picking/src/backend.rs
index c573d0e4b9..03bb26ee2e 100644
--- a/crates/bevy_picking/src/backend.rs
+++ b/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::{
diff --git a/crates/bevy_picking/src/input.rs b/crates/bevy_picking/src/input.rs
index 303c694bb4..bef8b57c47 100644
--- a/crates/bevy_picking/src/input.rs
+++ b/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;
 }
diff --git a/crates/bevy_picking/src/lib.rs b/crates/bevy_picking/src/lib.rs
index b2887bfbd6..29d294913b 100644
--- a/crates/bevy_picking/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_reflect/src/lib.rs b/crates/bevy_reflect/src/lib.rs
index 29829130fe..64216bfc09 100644
--- a/crates/bevy_reflect/src/lib.rs
+++ b/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)]
diff --git a/crates/bevy_render/src/lib.rs b/crates/bevy_render/src/lib.rs
index fc26a0c895..3393d0ef44 100644
--- a/crates/bevy_render/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_scene/src/lib.rs b/crates/bevy_scene/src/lib.rs
index b7bc473ca0..1fbf3b11b0 100644
--- a/crates/bevy_scene/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_sprite/src/lib.rs b/crates/bevy_sprite/src/lib.rs
index 1278b73fdb..152b612bd1 100644
--- a/crates/bevy_sprite/src/lib.rs
+++ b/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)]
diff --git a/crates/bevy_state/src/lib.rs b/crates/bevy_state/src/lib.rs
index b9ded18d4e..e8dc8264ef 100644
--- a/crates/bevy_state/src/lib.rs
+++ b/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)]
diff --git a/crates/bevy_tasks/src/lib.rs b/crates/bevy_tasks/src/lib.rs
index 1fe4f9511d..d8736d55ca 100644
--- a/crates/bevy_tasks/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_text/src/lib.rs b/crates/bevy_text/src/lib.rs
index 8922f0f103..4c379e61e5 100644
--- a/crates/bevy_text/src/lib.rs
+++ b/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};
diff --git a/crates/bevy_time/src/lib.rs b/crates/bevy_time/src/lib.rs
index 5181bc4335..8cb1c77ab8 100644
--- a/crates/bevy_time/src/lib.rs
+++ b/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};
 }
diff --git a/crates/bevy_transform/src/lib.rs b/crates/bevy_transform/src/lib.rs
index 0e170f111a..c6f5536292 100644
--- a/crates/bevy_transform/src/lib.rs
+++ b/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::*;
diff --git a/crates/bevy_ui/src/lib.rs b/crates/bevy_ui/src/lib.rs
index a9dcc9e270..948e52ebfa 100644
--- a/crates/bevy_ui/src/lib.rs
+++ b/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::{
diff --git a/crates/bevy_utils/src/lib.rs b/crates/bevy_utils/src/lib.rs
index 772d3fda31..b53bcd3e2e 100644
--- a/crates/bevy_utils/src/lib.rs
+++ b/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;
 }
diff --git a/crates/bevy_window/src/lib.rs b/crates/bevy_window/src/lib.rs
index fb0db3a27d..49d6e96f40 100644
--- a/crates/bevy_window/src/lib.rs
+++ b/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)]