From 514754d6503b2416e5266a24b39c884ab5d90d2f Mon Sep 17 00:00:00 2001 From: James Liu Date: Sun, 23 Jan 2022 18:00:43 +0000 Subject: [PATCH] Add crate level docs to bevy_log and enable #![warn(missing_docs)] (#3520) This PR is part of the issue #3492. # Objective - Add crate level docs to the bevy_log documentation to achieve a 100% documentation coverage. - Add the #![warn(missing_docs)] lint to keep the documentation coverage for the future. # Solution - Add and update the bevy_log crate level docs - Add a note about panicking from multiple `LogPlugins` per process. - Add the #![warn(missing_docs)] lint. --- crates/bevy_log/src/lib.rs | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/crates/bevy_log/src/lib.rs b/crates/bevy_log/src/lib.rs index 184b121484..c9e04cafde 100644 --- a/crates/bevy_log/src/lib.rs +++ b/crates/bevy_log/src/lib.rs @@ -1,7 +1,21 @@ +#![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). +//! +//! The macros provided for logging are reexported from [`tracing`](https://docs.rs/tracing), +//! and behave identically to it. +//! +//! By default, the [`LogPlugin`] from this crate is included in Bevy's `DefaultPlugins` +//! and the logging macros can be used out of the box, if used. +//! +//! For more fine-tuned control over logging behavior, insert a [`LogSettings`] resource before +//! adding [`LogPlugin`] or `DefaultPlugins` during app initialization. + #[cfg(target_os = "android")] mod android_tracing; 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, @@ -61,6 +75,12 @@ use tracing_subscriber::{prelude::*, registry::Registry, EnvFilter}; /// .run(); /// } /// ``` +/// +/// # Panics +/// +/// This plugin should not be added multiple times in the same process. This plugin +/// sets up global logging configuration for **all** Apps in a given process, and +/// rerunning the same initialization multiple times will lead to a panic. #[derive(Default)] pub struct LogPlugin;