Inverse missing_docs logic (#11676)

# Objective

Currently the `missing_docs` lint is allowed-by-default and enabled at
crate level when their documentations is complete (see #3492).
This PR proposes to inverse this logic by making `missing_docs`
warn-by-default and mark crates with imcomplete docs allowed.

## Solution

Makes `missing_docs` warn at workspace level and allowed at crate level
when the docs is imcomplete.

Cargo.toml

@@ -42,6 +42,7 @@ map_flatten = "warn"
 
 [workspace.lints.rust]
 unsafe_op_in_unsafe_fn = "warn"
+missing_docs = "warn"
 
 [lints]
 workspace = true

crates/bevy_a11y/src/lib.rs

@@ -1,6 +1,5 @@
 //! Accessibility for Bevy
 
-#![warn(missing_docs)]
 #![forbid(unsafe_code)]
 
 use std::sync::{

crates/bevy_animation/src/lib.rs

@@ -1,7 +1,5 @@
 //! Animation for the game engine Bevy
 
-#![warn(missing_docs)]
-
 mod animatable;
 mod util;
 

crates/bevy_app/src/lib.rs

@@ -1,7 +1,5 @@
 //! This crate is about everything concerning the highest-level, application layer of a Bevy app.
 
-#![warn(missing_docs)]
-
 mod app;
 mod main_schedule;
 mod plugin;

crates/bevy_asset/macros/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 use bevy_macro_utils::BevyManifest;
 use proc_macro::{Span, TokenStream};
 use quote::{format_ident, quote};

crates/bevy_asset/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 pub mod io;
 pub mod meta;
 pub mod processor;

crates/bevy_audio/src/lib.rs

@@ -21,7 +21,6 @@
 //! ```
 
 #![forbid(unsafe_code)]
-#![warn(missing_docs)]
 
 mod audio;
 mod audio_output;

crates/bevy_core/src/lib.rs

@@ -1,5 +1,3 @@
-#![warn(missing_docs)]
-
 //! This crate provides core functionality for Bevy Engine.
 
 mod name;

crates/bevy_core_pipeline/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 pub mod blit;
 pub mod bloom;
 pub mod contrast_adaptive_sharpening;

crates/bevy_derive/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 extern crate proc_macro;
 
 mod app_plugin;

crates/bevy_diagnostic/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 //! This crate provides a straightforward solution for integrating diagnostics in the [Bevy game engine](https://bevyengine.org/).
 //! It allows users to easily add diagnostic functionality to their Bevy applications, enhancing
 //! their ability to monitor and optimize their game's.

crates/bevy_dylib/src/lib.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 #![allow(clippy::single_component_path_imports)]
 
 //! Forces dynamic linking of Bevy.

crates/bevy_dynamic_plugin/src/lib.rs

@@ -1,5 +1,7 @@
 // FIXME(11590): remove this once the lint is fixed
 #![allow(unsafe_op_in_unsafe_fn)]
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
 
 mod loader;
 

crates/bevy_ecs/examples/change_detection.rs

@@ -1,14 +1,15 @@
+//! In this example we will simulate a population of entities. In every tick we will:
+//! 1. spawn a new entity with a certain possibility
+//! 2. age all entities
+//! 3. despawn entities with age > 2
+//!
+//! To demonstrate change detection, there are some console outputs based on changes in
+//! the `EntityCounter` resource and updated Age components
+
 use bevy_ecs::prelude::*;
 use rand::Rng;
 use std::ops::Deref;
 
-// In this example we will simulate a population of entities. In every tick we will:
-// 1. spawn a new entity with a certain possibility
-// 2. age all entities
-// 3. despawn entities with age > 2
-//
-// To demonstrate change detection, there are some console outputs based on changes in
-// the EntityCounter resource and updated Age components
 fn main() {
     // Create a new empty World to hold our Entities, Components and Resources
     let mut world = World::new();

crates/bevy_ecs/examples/events.rs

@@ -1,7 +1,8 @@
+//! In this example a system sends a custom event with a 50/50 chance during any frame.
+//! If an event was send, it will be printed by the console in a receiving system.
+
 use bevy_ecs::prelude::*;
 
-// In this example a system sends a custom event with a 50/50 chance during any frame.
-// If an event was send, it will be printed by the console in a receiving system.
 fn main() {
     // Create a new empty world and add the event as a resource
     let mut world = World::new();

crates/bevy_ecs/examples/resources.rs

@@ -1,9 +1,10 @@
+//! In this example we add a counter resource and increase it's value in one system,
+//! while a different system prints the current count to the console.
+
 use bevy_ecs::prelude::*;
 use rand::Rng;
 use std::ops::Deref;
 
-// In this example we add a counter resource and increase it's value in one system,
-// while a different system prints the current count to the console.
 fn main() {
     // Create a world
     let mut world = World::new();

crates/bevy_ecs/macros/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 extern crate proc_macro;
 
 mod component;

crates/bevy_ecs/src/lib.rs

@@ -1,6 +1,5 @@
 // FIXME(11590): remove this once the lint is fixed
 #![allow(unsafe_op_in_unsafe_fn)]
-#![warn(missing_docs)]
 #![doc = include_str!("../README.md")]
 
 #[cfg(target_pointer_width = "16")]

crates/bevy_encase_derive/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 use bevy_macro_utils::BevyManifest;
 use encase_derive_impl::{implement, syn};
 

crates/bevy_gilrs/src/lib.rs

@@ -3,8 +3,6 @@
 //! This crate is built on top of [GilRs](gilrs), a library
 //! that handles abstracting over platform-specific gamepad APIs.
 
-#![warn(missing_docs)]
-
 mod converter;
 mod gilrs_system;
 mod rumble;

crates/bevy_gizmos/src/lib.rs

@@ -1,5 +1,3 @@
-#![warn(missing_docs)]
-
 //! This crate adds an immediate mode drawing api to Bevy for visual debugging.
 //!
 //! # Example
@@ -79,7 +77,7 @@ use bevy_render::{
     renderer::RenderDevice,
     Extract, ExtractSchedule, Render, RenderApp, RenderSet,
 };
-use bevy_utils::{tracing::warn, HashMap};
+use bevy_utils::HashMap;
 use config::{
     DefaultGizmoConfigGroup, GizmoConfig, GizmoConfigGroup, GizmoConfigStore, GizmoMeshConfig,
 };

crates/bevy_gltf/src/lib.rs

@@ -3,8 +3,6 @@
 //!
 //! The [glTF 2.0 specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html) defines the format of the glTF files.
 
-#![warn(missing_docs)]
-
 #[cfg(feature = "bevy_animation")]
 use bevy_animation::AnimationClip;
 use bevy_utils::HashMap;

crates/bevy_hierarchy/src/lib.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 //! Parent-child relationships for Bevy entities.
 //!
 //! You should use the tools in this crate

crates/bevy_input/src/lib.rs

@@ -1,5 +1,3 @@
-#![warn(missing_docs)]
-
 //! Input functionality for the [Bevy game engine](https://bevyengine.org/).
 //!
 //! # Supported input devices

crates/bevy_internal/src/lib.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 //! This module is separated into its own crate to enable simple dynamic linking for Bevy, and should not be used directly
 
 /// `use bevy::prelude::*;` to import common components, bundles, and plugins.

crates/bevy_log/src/lib.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 //! This crate provides logging functions and configuration for [Bevy](https://bevyengine.org)
 //! apps, and automatically configures platform specific log handlers (i.e. WASM or Android).
 //!

crates/bevy_macro_utils/src/lib.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 #![deny(unsafe_code)]
 //! A collection of helper types and functions for working on macros within the Bevy ecosystem.
 

crates/bevy_math/src/lib.rs

@@ -4,8 +4,6 @@
 //! matrices like [`Mat2`], [`Mat3`] and [`Mat4`] and orientation representations
 //! like [`Quat`].
 
-#![warn(missing_docs)]
-
 mod affine3;
 mod aspect_ratio;
 pub mod bounding;

crates/bevy_mikktspace/examples/generate.rs

@@ -1,8 +1,10 @@
+//! This example demonstrates how to generate a mesh.
+
 #![allow(clippy::bool_assert_comparison, clippy::useless_conversion)]
 
 use glam::{Vec2, Vec3};
 
-pub type Face = [u32; 3];
+type Face = [u32; 3];
 
 #[derive(Debug)]
 struct Vertex {

crates/bevy_mikktspace/src/lib.rs

@@ -3,6 +3,8 @@
     clippy::all,
     clippy::undocumented_unsafe_blocks
 )]
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
 
 use glam::{Vec2, Vec3};
 

crates/bevy_pbr/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 pub mod wireframe;
 
 mod alpha;

crates/bevy_ptr/src/lib.rs

@@ -1,6 +1,5 @@
 #![doc = include_str!("../README.md")]
 #![no_std]
-#![warn(missing_docs)]
 
 use core::fmt::{self, Formatter, Pointer};
 use core::{

crates/bevy_reflect/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 //! Reflection in Rust.
 //!
 //! [Reflection] is a powerful tool provided within many programming languages

crates/bevy_reflect/src/path/mod.rs

@@ -1,5 +1,3 @@
-#![warn(missing_docs)]
-
 pub mod access;
 pub use access::*;
 

crates/bevy_render/macros/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 mod as_bind_group;
 mod extract_component;
 mod extract_resource;

crates/bevy_render/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 #[cfg(target_pointer_width = "16")]
 compile_error!("bevy_render cannot compile for a 16-bit platform.");
 

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

@@ -19,8 +19,6 @@
 //! # }
 //! ```
 
-#![warn(missing_docs)]
-
 mod dim2;
 pub use dim2::{CircleMeshBuilder, EllipseMeshBuilder};
 

crates/bevy_scene/src/lib.rs

@@ -4,8 +4,6 @@
 //! instantiated or removed from a world to allow composition. Scenes can be serialized/deserialized,
 //! for example to save part of the world state to a file.
 
-#![warn(missing_docs)]
-
 mod bundle;
 mod dynamic_scene;
 mod dynamic_scene_builder;

crates/bevy_sprite/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 //! Provides 2D sprite rendering functionality.
 mod bundle;
 mod dynamic_texture_atlas_builder;

crates/bevy_tasks/examples/busy_behavior.rs

@@ -1,10 +1,10 @@
+//! This sample demonstrates creating a thread pool with 4 tasks and spawning 40 tasks that spin
+//! for 100ms. It's expected to take about a second to run (assuming the machine has >= 4 logical
+//! cores)
+
 use bevy_tasks::TaskPoolBuilder;
 use web_time::{Duration, Instant};
 
-// This sample demonstrates creating a thread pool with 4 tasks and spawning 40 tasks that spin
-// for 100ms. It's expected to take about a second to run (assuming the machine has >= 4 logical
-// cores)
-
 fn main() {
     let pool = TaskPoolBuilder::new()
         .thread_name("Busy Behavior ThreadPool".to_string())

crates/bevy_tasks/examples/idle_behavior.rs

@@ -1,10 +1,10 @@
+//! This sample demonstrates a thread pool with one thread per logical core and only one task
+//! spinning. Other than the one thread, the system should remain idle, demonstrating good behavior
+//! for small workloads.
+
 use bevy_tasks::TaskPoolBuilder;
 use web_time::{Duration, Instant};
 
-// This sample demonstrates a thread pool with one thread per logical core and only one task
-// spinning. Other than the one thread, the system should remain idle, demonstrating good behavior
-// for small workloads.
-
 fn main() {
     let pool = TaskPoolBuilder::new()
         .thread_name("Idle Behavior ThreadPool".to_string())

crates/bevy_tasks/src/lib.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 #![doc = include_str!("../README.md")]
 
 mod slice;

crates/bevy_text/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 mod error;
 mod font;
 mod font_atlas;

crates/bevy_time/src/lib.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 #![doc = include_str!("../README.md")]
 
 /// Common run conditions

crates/bevy_transform/src/lib.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 #![doc = include_str!("../README.md")]
 
 pub mod commands;

crates/bevy_ui/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 //! This crate contains Bevy's UI system, which can be used to create UI for both 2D and 3D games
 //! # Basic usage
 //! Spawn UI elements with [`node_bundles::ButtonBundle`], [`node_bundles::ImageBundle`], [`node_bundles::TextBundle`] and [`node_bundles::NodeBundle`]

crates/bevy_utils/macros/src/lib.rs

@@ -1,3 +1,6 @@
+// FIXME(3492): remove once docs are ready
+#![allow(missing_docs)]
+
 use proc_macro::TokenStream;
 use quote::{format_ident, quote};
 use syn::{

crates/bevy_utils/src/lib.rs

@@ -3,8 +3,6 @@
 //! [Bevy]: https://bevyengine.org/
 //!
 
-#![warn(missing_docs)]
-
 #[allow(missing_docs)]
 pub mod prelude {
     pub use crate::default;

crates/bevy_window/src/lib.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 //! `bevy_window` provides a platform-agnostic interface for windowing in Bevy.
 //!
 //! This crate contains types for window management and events,