Clarify doc around systems

README.md

@@ -47,6 +47,35 @@ App::default()
     .run();
 ```
 
+This provides the basic setup for using 🍃 Bevy Tweening. However, additional setup is required depending on the components and assets you want to animate:
+
+- To ensure a component `C` is animated, the `component_animator_system::<C>` system must run each frame, in addition of adding an `Animator::<C>` component to the same Entity as `C`.
+
+- To ensure an asset `A` is animated, the `asset_animator_system::<A>` system must run each frame, in addition of adding an `AssetAnimator<A>` component to any Entity. Animating assets also requires the `bevy_asset` feature (enabled by default).
+
+By default, 🍃 Bevy Tweening adopts a minimalist approach, and the `TweeningPlugin` will only add systems to animate components and assets for which a `Lens` is provided by 🍃 Bevy Tweening itself. This means that any other Bevy component or asset (either built-in from Bevy itself, or custom) requires manually scheduling the appropriate system.
+
+| Component or Asset | Animation system added by `TweeningPlugin`? |
+|---|---|
+| `Transform`          | Yes                           |
+| `Sprite`             | Only if `bevy_sprite` feature |
+| `ColorMaterial`      | Only if `bevy_sprite` feature |
+| `Style`              | Only if `bevy_ui` feature     |
+| `Text`               | Only if `bevy_text` feature   |
+| All other components | No                            |
+
+To add a system for a component `C`, use:
+
+```rust
+app.add_systems(Update, component_animator_system::<C>.in_set(AnimationSystem::AnimationUpdate));
+```
+
+Similarly for an asset `A`, use:
+
+```rust
+app.add_systems(Update, asset_animator_system::<A>.in_set(AnimationSystem::AnimationUpdate));
+```
+
 ### Animate a component
 
 Animate the transform position of an entity by creating a `Tween` animation for the transform, and adding an `Animator` component with that tween:
@@ -170,7 +199,7 @@ The two formulations are mathematically equivalent, but one may be more suited t
 
 ## Custom component support
 
-Custom components are animated like built-in Bevy ones, via a lens.
+Custom components are animated via a lens like the ones described in (Bevy Components)[#bevy-components].
 
 ```rust
 #[derive(Component)]
@@ -188,11 +217,11 @@ impl Lens<MyCustomComponent> for MyCustomLens {
 }
 ```
 
-Then, in addition, the system `component_animator_system::<CustomComponent>` needs to be added to the application. This system will extract each frame all `CustomComponent` instances with an `Animator<CustomComponent>` on the same entity, and animate the component via its animator.
+Then, in addition, the system `component_animator_system::<CustomComponent>` needs to be added to the application, as described in [System Setup](#system-setup). This system will extract each frame all `CustomComponent` instances with an `Animator<CustomComponent>` on the same entity, and animate the component via its animator.
 
 ## Custom asset support
 
-The process is similar to custom components, creating a custom lens for the custom asset. The system to add is `asset_animator_system::<CustomAsset>`. This requires the `bevy_asset` feature (enabled by default).
+The process is similar to custom components, creating a custom lens for the custom asset. The system to add is `asset_animator_system::<CustomAsset>`, as described in [System Setup](#system-setup). This requires the `bevy_asset` feature (enabled by default).
 
 ## Examples
 

src/lib.rs

@@ -64,6 +64,56 @@
 //! # }
 //! ```
 //!
+//! Note that this example leverages the fact [`TweeningPlugin`] automatically
+//! adds the necessary system to animate [`Transform`] components. However, for
+//! most other components and assets, you need to manually add those systems to
+//! your `App`.
+//!
+//! # System setup
+//!
+//! Adding the [`TweeningPlugin`] to your app provides the basic setup for using
+//! 🍃 Bevy Tweening. However, additional setup is required depending on the
+//! components and assets you want to animate:
+//!
+//! - To ensure a component `C` is animated, the
+//!   [`component_animator_system::<C>`] system must run each frame, in addition
+//!   of adding an [`Animator::<C>`] component to the same Entity as `C`.
+//!
+//! - To ensure an asset `A` is animated, the [`asset_animator_system::<A>`]
+//!   system must run each frame, in addition of adding an [`AssetAnimator<A>`]
+//!   component to any Entity. Animating assets also requires the `bevy_asset`
+//!   feature (enabled by default).
+//!
+//! By default, 🍃 Bevy Tweening adopts a minimalist approach, and the
+//! [`TweeningPlugin`] will only add systems to animate components and assets
+//! for which a [`Lens`] is provided by 🍃 Bevy Tweening itself. This means that
+//! any other Bevy component or asset (either built-in from Bevy itself, or
+//! custom) requires manually scheduling the appropriate system.
+//!
+//! | Component or Asset | Animation system added by `TweeningPlugin`? |
+//! |---|---|
+//! | [`Transform`]          | Yes                           |
+//! | [`Sprite`]             | Only if `bevy_sprite` feature |
+//! | [`ColorMaterial`]      | Only if `bevy_sprite` feature |
+//! | [`Style`]              | Only if `bevy_ui` feature     |
+//! | [`Text`]               | Only if `bevy_text` feature   |
+//! | All other components   | No                            |
+//!
+//! To add a system for a component `C`, use:
+//!
+//! ```
+//! # use bevy::prelude::*;
+//! # use bevy_tweening::*;
+//! # let mut app = App::default();
+//! # #[derive(Component)] struct C;
+//! app.add_systems(Update,
+//!     component_animator_system::<C>
+//!         .in_set(AnimationSystem::AnimationUpdate));
+//! ```
+//!
+//! Similarly for an asset `A`, use the `asset_animator_system`. This is only
+//! available with the `bevy_asset` feature.
+//!
 //! # Tweenables
 //!
 //! 🍃 Bevy Tweening supports several types of _tweenables_, building blocks
@@ -150,6 +200,8 @@
 //! [`Query`]: https://docs.rs/bevy/0.11.0/bevy/ecs/system/struct.Query.html
 //! [`ColorMaterial`]: https://docs.rs/bevy/0.11.0/bevy/sprite/struct.ColorMaterial.html
 //! [`Sprite`]: https://docs.rs/bevy/0.11.0/bevy/sprite/struct.Sprite.html
+//! [`Style`]: https://docs.rs/bevy/0.11.0/bevy/ui/struct.Style.html
+//! [`Text`]: https://docs.rs/bevy/0.11.0/bevy/text/struct.Text.html
 //! [`Transform`]: https://docs.rs/bevy/0.11.0/bevy/transform/components/struct.Transform.html
 
 use std::time::Duration;

src/plugin.rs

@@ -79,7 +79,7 @@ pub enum AnimationSystem {
 
 /// Animator system for components.
 ///
-/// This system extracts all components of type `T` with an `Animator<T>`
+/// This system extracts all components of type `T` with an [`Animator<T>`]
 /// attached to the same entity, and tick the animator to animate the component.
 pub fn component_animator_system<T: Component>(
     time: Res<Time>,
@@ -103,7 +103,7 @@ pub fn component_animator_system<T: Component>(
 
 /// Animator system for assets.
 ///
-/// This system ticks all `AssetAnimator<T>` components to animate their
+/// This system ticks all [`AssetAnimator<T>`] components to animate their
 /// associated asset.
 ///
 /// This requires the `bevy_asset` feature (enabled by default).
@@ -227,8 +227,8 @@ mod tests {
         let transform = env.transform();
         assert!(transform.is_changed());
 
-        //fn nit() {}
-        //let mut system = IntoSystem::into_system(nit);
+        // fn nit() {}
+        // let mut system = IntoSystem::into_system(nit);
         let mut system = IntoSystem::into_system(component_animator_system::<Transform>);
         system.initialize(env.world_mut());