Add bevy_hierarchy Crate and plugin documentation (bevyengine#10951)

This PR is part of a project aimed at improving the API documentation of
`bevy_hierarchy`. Other PRs will be based on this.

This PR in particular is also an experiment in providing a high level
overview of the tools provided by a Bevy plugin/crate. It also provides
general information about universal invariants, so statement repetition
in crate items can be dramatically reduced.

## Other changes

The other PRs of this project that expand on this one:

- bevyengine#10952
- bevyengine#10953
- bevyengine#10954
- bevyengine#10955
- bevyengine#10956
- bevyengine#10957

---------

Co-authored-by: GitGhillie <[email protected]>

crates/bevy_hierarchy/src/lib.rs

@@ -1,8 +1,50 @@
 #![warn(missing_docs)]
-//! `bevy_hierarchy` can be used to define hierarchies of entities.
+//! Parent-child relationships for Bevy entities.
 //!
-//! Most commonly, these hierarchies are used for inheriting `Transform` values
-//! from the [`Parent`] to its [`Children`].
+//! You should use the tools in this crate
+//! whenever you want to organize your entities in a hierarchical fashion,
+//! to make groups of entities more manageable,
+//! or to propagate properties throughout the entity hierarchy.
+//!
+//! This crate introduces various tools, including a [plugin]
+//! for managing parent-child relationships between entities.
+//! It provides two components, [`Parent`] and [`Children`],
+//! to store references to related entities.
+//! It also provides [command] and [world] API extensions
+//! to set and clear those relationships.
+//!
+//! More advanced users may also appreciate
+//! [query extension methods] to traverse hierarchies,
+//! and [events] to notify hierarchical changes.
+//! There is also a [diagnostic plugin] to validate property propagation.
+//!
+//! # Hierarchy management
+//!
+//! The methods defined in this crate fully manage
+//! the components responsible for defining the entity hierarchy.
+//! Mutating these components manually may result in hierarchy invalidation.
+//!
+//! Hierarchical relationships are always managed symmetrically.
+//! For example, assigning a child to an entity
+//! will always set the parent in the other,
+//! and vice versa.
+//! Similarly, unassigning a child in the parent
+//! will always unassign the parent in the child.
+//!
+//! ## Despawning entities
+//!
+//! The commands and methods provided by `bevy_ecs` to despawn entities
+//! are not capable of automatically despawning hierarchies of entities.
+//! In most cases, these operations will invalidate the hierarchy.
+//! Instead, you should use the provided [hierarchical despawn extension methods].
+//!
+//! [command]: BuildChildren
+//! [diagnostic plugin]: ValidParentCheckPlugin
+//! [events]: HierarchyEvent
+//! [hierarchical despawn extension methods]: DespawnRecursiveExt
+//! [plugin]: HierarchyPlugin
+//! [query extension methods]: HierarchyQueryExt
+//! [world]: BuildWorldChildren
 
 mod components;
 pub use components::*;
@@ -35,7 +77,11 @@ pub mod prelude {
 #[cfg(feature = "bevy_app")]
 use bevy_app::prelude::*;
 
-/// The base plugin for handling [`Parent`] and [`Children`] components
+/// Provides hierarchy functionality to a Bevy app.
+///
+/// Check the [crate-level documentation] for all the features.
+///
+/// [crate-level documentation]: crate
 #[derive(Default)]
 pub struct HierarchyPlugin;