From 02e8658ffea06cfd62d6ee6bcd6ddfc54f237c4d Mon Sep 17 00:00:00 2001 From: Ben Frankel Date: Sun, 18 Aug 2024 19:19:05 -0700 Subject: [PATCH] Write documentation --- src/context.rs | 6 ++-- src/lib.rs | 82 +++++++++++++++++++++++++++++++++++++++--------- src/placement.rs | 6 ++-- 3 files changed, 72 insertions(+), 22 deletions(-) diff --git a/src/context.rs b/src/context.rs index 56c363e..b2d6c74 100644 --- a/src/context.rs +++ b/src/context.rs @@ -1,5 +1,3 @@ -//! TODO - use bevy_app::{App, PreUpdate}; #[cfg(feature = "bevy_reflect")] use bevy_ecs::reflect::ReflectResource; @@ -39,7 +37,7 @@ pub(super) fn plugin(app: &mut App) { ); } -/// TODO +/// A [`Resource`] that contains the current values in use by the tooltip system. #[derive(Resource, Clone, Debug)] #[cfg_attr( feature = "bevy_reflect", @@ -203,7 +201,7 @@ fn update_tooltip_context( } } -/// TODO +/// The current state of the tooltip system. #[derive(Copy, Clone, Debug)] #[cfg_attr(feature = "bevy_reflect", derive(bevy_reflect::Reflect))] pub(crate) enum TooltipState { diff --git a/src/lib.rs b/src/lib.rs index 69d73dd..282cc94 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,9 +1,39 @@ -//! TODO +//! Featureful tooltips for Bevy. +//! +//! # Getting started +//! +//! Import the [prelude] to bring common types into scope: +//! +//! ``` +//! use pyri_tooltip::prelude::*; +//! ``` +//! +//! Add [`TooltipPlugin`] to set up the tooltip system: +//! +//! ```ignore +//! app.add_plugins(TooltipPlugin::default()); +//! ``` +//! +//! Spawn a UI node with a [`Tooltip`]: +//! +//! ```ignore +//! commands.spawn(( +//! NodeBundle::default(), +//! Interaction::default(), +//! Tooltip::from_section("Hello, world!", TextStyle::default()), +//! )); +//! ``` mod context; mod placement; -/// TODO +/// Re-exports for commonly used types. +/// +/// # Usage +/// +/// ``` +/// use pyri_tooltip::prelude::*; +/// ``` pub mod prelude { pub use super::{ PrimaryTooltip, Tooltip, TooltipActivation, TooltipEntity, TooltipPlacement, TooltipPlugin, @@ -27,14 +57,19 @@ use bevy_ui::{ pub use placement::TooltipPlacement; -/// TODO +/// A [`Plugin`] that sets up the tooltip widget system. #[derive(Default)] pub struct TooltipPlugin { - // TODO: Write about the components expected to exist on this entity (or insert them myself). - /// Set a custom entity for [`PrimaryTooltip::container`], or spawn a default entity if `None`. + /// Set a custom entity for [`PrimaryTooltip::container`], or spawn the default container + /// entity if `None`. + /// + /// This entity should include all of the components of [`NodeBundle`], with + /// [`Visibility::Hidden`] and [`Style::position_type`] set to [`PositionType::Absolute`]. pub container: Option, - // TODO: Write about the components expected to exist on this entity (or insert them myself). - /// Set a custom entity for [`PrimaryTooltip::text`], or spawn a default entity if `None`. + /// Set a custom entity for [`PrimaryTooltip::text`], or spawn the default text entity if + /// `None`. + /// + /// This entity should include all of the components of [`TextBundle`]. pub text: Option, } @@ -50,7 +85,9 @@ impl Plugin for TooltipPlugin { } } -/// TODO +/// A [`Resource`] containing the [`Entity`] IDs of the global primary tooltip. +/// +/// See [`TooltipPlugin`] to set up a custom primary tooltip. #[derive(Resource, Copy, Clone, Debug)] #[cfg_attr( feature = "bevy_reflect", @@ -97,7 +134,16 @@ impl PrimaryTooltip { } // TODO: Animation, wedge (like a speech bubble), easier content customization / icons. -/// TODO +/// A [`Component`] that specifies a tooltip to be displayed on hover. +/// +/// This will only work on entities that also include the following components: +/// - [`NodeBundle`] components +/// - [`Interaction`](bevy_ui::Interaction) +/// +/// The default behavior consists of the following values: +/// - [`TooltipActivation::IDLE`] +/// - [`TooltipTransfer::NONE`] +/// - [`TooltipPlacement::CURSOR`] #[derive(Component)] #[cfg_attr( feature = "bevy_reflect", @@ -116,7 +162,7 @@ pub struct Tooltip { } impl Tooltip { - /// Use the given tooltip entity and default behavior. + /// Use the provided tooltip entity and default behavior. fn new(entity: TooltipEntity) -> Self { Self { activation: TooltipActivation::IDLE, @@ -165,7 +211,9 @@ impl Tooltip { } } -/// TODO +/// The tooltip activation and dismissal conditions. +/// +/// Defaults to [`Self::IMMEDIATE`]. #[derive(Copy, Clone, Debug)] #[cfg_attr(feature = "bevy_reflect", derive(bevy_reflect::Reflect))] pub struct TooltipActivation { @@ -235,13 +283,17 @@ impl Default for TooltipActivation { } } -/// TODO +/// The tooltip transfer conditions. +/// +/// When a transfer occurs, the next tooltip's activation delay will be skipped. +/// +/// Defaults to [`Self::NONE`]. #[derive(Copy, Clone, Debug)] #[cfg_attr(feature = "bevy_reflect", derive(bevy_reflect::Reflect))] pub struct TooltipTransfer { - /// Only transfer to elements in the same group, or to self if `None`. + /// Only transfer to elements within the same group, or to self if `None`. pub group: Option, - /// Only transfer to elements in the same layer or lower. + /// Only transfer to elements within the same layer or lower. pub layer: i8, /// Only transfer within this duration after the cursor moves away from the old target (in milliseconds). pub timeout: u16, @@ -273,7 +325,7 @@ impl Default for TooltipTransfer { } } -/// TODO +/// The tooltip entity and content to be displayed. #[derive(Clone, Debug)] #[cfg_attr(feature = "bevy_reflect", derive(bevy_reflect::Reflect))] pub enum TooltipEntity { diff --git a/src/placement.rs b/src/placement.rs index a5abe38..ee8e90d 100644 --- a/src/placement.rs +++ b/src/placement.rs @@ -1,5 +1,3 @@ -//! TODO - use bevy_app::{App, PostUpdate}; use bevy_ecs::{ entity::Entity, @@ -32,7 +30,9 @@ pub(super) fn plugin(app: &mut App) { ); } -/// TODO +/// The tooltip placement configuration. +/// +/// Defaults to [`Self::CURSOR_CENTERED`]. #[derive(Copy, Clone, Debug)] #[cfg_attr(feature = "bevy_reflect", derive(bevy_reflect::Reflect))] pub struct TooltipPlacement {