docs: add more docs

crates/composition/src/event_loop.rs

@@ -14,6 +14,10 @@ pub trait FromAppState<'a> {
     fn from_app_state(app_state: &'a mut AppState) -> Self;
 }
 
+/// Main event loop for the shell runtime
+///
+/// Manages the Wayland event loop and custom event sources.
+/// Created internally by `Shell` and started via `Shell::run()`.
 pub struct ShellEventLoop {
     inner: Rc<RefCell<dyn WaylandSystemOps>>,
 }
@@ -33,6 +37,10 @@ impl ShellEventLoop {
     }
 }
 
+/// Handle for registering custom event sources with the event loop
+///
+/// Allows adding timers, channels, and file descriptors to the event loop.
+/// Obtained via `Shell::event_loop_handle()`.
 pub struct EventLoopHandle {
     system: Weak<RefCell<dyn WaylandSystemOps>>,
 }
@@ -42,6 +50,9 @@ impl EventLoopHandle {
         Self { system }
     }
 
+    /// Register a custom event source with the event loop
+    ///
+    /// Returns a registration token that can be used to remove the source later.
     pub fn insert_source<S, F, R>(&self, source: S, callback: F) -> Result<RegistrationToken>
     where
         S: EventSource<Ret = R> + 'static,
@@ -60,6 +71,9 @@ impl EventLoopHandle {
         })
     }
 
+    /// Add a timer that fires after the specified duration
+    ///
+    /// Callback receives the deadline and can return `TimeoutAction::ToInstant` to reschedule.
     pub fn add_timer<F>(&self, duration: Duration, mut callback: F) -> Result<RegistrationToken>
     where
         F: FnMut(Instant, &mut AppState) -> TimeoutAction + 'static,
@@ -70,6 +84,9 @@ impl EventLoopHandle {
         })
     }
 
+    /// Add a timer that fires at a specific instant
+    ///
+    /// Callback receives the deadline and can return `TimeoutAction::ToInstant` to reschedule.
     pub fn add_timer_at<F>(&self, deadline: Instant, mut callback: F) -> Result<RegistrationToken>
     where
         F: FnMut(Instant, &mut AppState) -> TimeoutAction + 'static,
@@ -80,6 +97,9 @@ impl EventLoopHandle {
         })
     }
 
+    /// Add a channel for sending messages to the event loop from any thread
+    ///
+    /// Returns a registration token and sender. Messages sent via the sender trigger the callback.
     pub fn add_channel<T, F>(
         &self,
         mut callback: F,
@@ -97,6 +117,9 @@ impl EventLoopHandle {
         Ok((token, sender))
     }
 
+    /// Add a file descriptor to be monitored for readability or writability
+    ///
+    /// Callback is invoked when the file descriptor becomes ready according to the interest.
     pub fn add_fd<F, T>(
         &self,
         fd: T,

crates/composition/src/lib.rs

@@ -54,8 +54,10 @@ pub mod calloop {
     pub use layer_shika_adapters::platform::calloop::*;
 }
 
+/// Result type alias using layer-shika's Error
 pub type Result<T> = StdResult<T, Error>;
 
+/// Error types for layer-shika operations
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
     #[error("Adapter error: {0}")]

crates/composition/src/selection.rs

@@ -5,6 +5,11 @@ use crate::{
 };
 use layer_shika_domain::errors::DomainError;
 
+/// A selection of surfaces matching a selector
+///
+/// Provides methods to interact with all matching surfaces at once, such as
+/// setting up callbacks, modifying properties, or accessing component instances.
+/// Created via `Shell::select()`.
 pub struct Selection<'a> {
     shell: &'a Shell,
     selector: Selector,

crates/composition/src/selector.rs

@@ -2,19 +2,31 @@ use crate::{OutputHandle, OutputInfo};
 use std::fmt::{Debug, Formatter, Result as FmtResult};
 use std::sync::Arc;
 
+/// Runtime information about a surface instance
 #[derive(Debug, Clone)]
 pub struct SurfaceInfo {
+    /// Surface component name
     pub name: String,
+    /// Handle to the output displaying this surface
     pub output: OutputHandle,
 }
 
+/// Selector for targeting surfaces when setting up callbacks or runtime configuration
+///
+/// Use `Surface::named()` to target a specific surface, or combine selectors for complex targeting.
 #[derive(Clone)]
 pub enum Surface {
+    /// Select all surfaces
     All,
+    /// Select surface by exact name
     Named(String),
+    /// Select any surface matching one of the given names
     Any(Vec<String>),
+    /// Select surfaces matching a custom predicate
     Filter(Arc<dyn Fn(&SurfaceInfo) -> bool + Send + Sync>),
+    /// Invert selection
     Not(Box<Surface>),
+    /// Union of multiple selectors
     Or(Vec<Surface>),
 }
 
@@ -86,15 +98,24 @@ impl Debug for Surface {
     }
 }
 
+/// Selector for targeting outputs (monitors) in runtime operations
 #[derive(Clone)]
 pub enum Output {
+    /// Select all outputs
     All,
+    /// Select the primary output
     Primary,
+    /// Select the currently active output
     Active,
+    /// Select output by handle
     Handle(OutputHandle),
+    /// Select output by name
     Named(String),
+    /// Select outputs matching a custom predicate
     Filter(Arc<dyn Fn(&OutputInfo) -> bool + Send + Sync>),
+    /// Invert selection
     Not(Box<Output>),
+    /// Union of multiple selectors
     Or(Vec<Output>),
 }
 
@@ -179,6 +200,10 @@ impl Debug for Output {
     }
 }
 
+/// Combined surface and output selector for precise targeting
+///
+/// Combines a surface selector with an output selector to target specific
+/// surface instances on specific outputs.
 #[derive(Clone, Debug)]
 pub struct Selector {
     pub surface: Surface,

crates/composition/src/shell.rs

@@ -31,6 +31,7 @@ use std::cell::RefCell;
 use std::path::{Path, PathBuf};
 use std::rc::Rc;
 
+/// Default Slint component name used when none is specified
 pub const DEFAULT_COMPONENT_NAME: &str = "Main";
 
 enum CompilationSource {
@@ -39,6 +40,10 @@ enum CompilationSource {
     Compiled(Rc<CompilationResult>),
 }
 
+/// Builder for configuring and creating a Shell with one or more surfaces
+///
+/// Created via `Shell::from_file()`, `Shell::from_source()`, or `Shell::from_compilation()`.
+/// Chain `.surface()` calls to configure multiple surfaces, then call `.build()` or `.run()`.
 pub struct ShellBuilder {
     compilation: CompilationSource,
     surfaces: Vec<SurfaceDefinition>,
@@ -118,6 +123,11 @@ impl ShellBuilder {
     }
 }
 
+/// Builder for configuring a single surface within a Shell
+///
+/// Created by calling `.surface()` on `ShellBuilder`. Chain configuration methods
+/// like `.height()`, `.anchor()`, `.exclusive_zone()`, then either start a new surface
+/// with `.surface()` or finalize with `.build()` or `.run()`.
 pub struct SurfaceConfigBuilder {
     shell_builder: ShellBuilder,
     component: String,
@@ -218,6 +228,10 @@ impl SurfaceConfigBuilder {
 type OutputConnectedHandler = Box<dyn Fn(&OutputInfo)>;
 type OutputDisconnectedHandler = Box<dyn Fn(OutputHandle)>;
 
+/// Main runtime for managing Wayland layer-shell surfaces with Slint UI
+///
+/// Manages the lifecycle of one or more layer surfaces, event loop integration,
+/// and Slint component instantiation. Create via builder methods or `from_config()`.
 pub struct Shell {
     inner: Rc<RefCell<dyn WaylandSystemOps>>,
     registry: SurfaceRegistry,
@@ -1069,6 +1083,9 @@ impl ShellRuntime for Shell {
     }
 }
 
+/// Context providing access to shell state within custom event source callbacks
+///
+/// Obtained via event source callbacks registered through `EventLoopHandle`.
 pub struct ShellEventContext<'a> {
     app_state: &'a mut AppState,
 }

crates/composition/src/shell_config.rs

@@ -3,9 +3,15 @@ use layer_shika_domain::prelude::{SurfaceConfig, UiSource};
 use std::path::PathBuf;
 use std::rc::Rc;
 
+/// Source for Slint UI definition
+///
+/// Specifies where to load the UI from: a `.slint` file, inline source code, or pre-compiled result.
 pub enum CompiledUiSource {
+    /// Load UI from a `.slint` file path
     File(PathBuf),
+    /// Parse UI from source code string
     Source(String),
+    /// Use pre-compiled Slint result
     Compiled(Rc<CompilationResult>),
 }
 
@@ -56,14 +62,21 @@ impl From<PathBuf> for CompiledUiSource {
     }
 }
 
+/// Declarative configuration for creating a shell with multiple surfaces
+///
+/// Use this for programmatic or externally-driven configuration.
+/// For fluent builder API, use `Shell::from_file()` instead.
 pub struct ShellConfig {
     pub ui_source: CompiledUiSource,
     pub surfaces: Vec<SurfaceComponentConfig>,
 }
 
+/// Associates a Slint component name with its surface configuration
 #[derive(Debug, Clone)]
 pub struct SurfaceComponentConfig {
+    /// Name of the Slint component to instantiate
     pub component: String,
+    /// Surface configuration for this component
     pub config: SurfaceConfig,
 }
 

crates/composition/src/shell_runtime.rs

@@ -1,7 +1,9 @@
 use layer_shika_adapters::platform::slint_interpreter::ComponentInstance;
 
+/// Default surface name used internally
 pub const DEFAULT_SURFACE_NAME: &str = "main";
 
+/// Trait providing runtime access to shell components and event loop
 pub trait ShellRuntime {
     type LoopHandle;
     type Context<'a>;

crates/composition/src/system.rs

@@ -79,6 +79,10 @@ pub enum ShellCommand {
     Render,
 }
 
+/// Handle for runtime control of shell operations
+///
+/// Provides methods to manipulate surfaces, show popups, and request redraws.
+/// Obtained from callbacks via the control parameter.
 #[derive(Clone)]
 pub struct ShellControl {
     sender: channel::Sender<ShellCommand>,
@@ -166,6 +170,10 @@ impl ShellControl {
     }
 }
 
+/// Handle for runtime control of a specific surface
+///
+/// Allows modifying surface properties like size, anchor, layer, and margins at runtime.
+/// Obtained via `ShellControl::surface()`.
 pub struct SurfaceControlHandle {
     name: String,
     sender: channel::Sender<ShellCommand>,
@@ -316,6 +324,10 @@ impl SurfaceControlHandle {
     }
 }
 
+/// Builder for applying multiple configuration changes to a surface at once
+///
+/// Created via `SurfaceControlHandle::configure()`. Chain configuration methods
+/// and call `.apply()` to commit all changes atomically.
 pub struct RuntimeSurfaceConfigBuilder {
     handle: SurfaceControlHandle,
     config: SurfaceConfig,

crates/domain/src/config.rs

@@ -6,6 +6,10 @@ use crate::value_objects::layer::Layer;
 use crate::value_objects::margins::Margins;
 use crate::value_objects::output_policy::OutputPolicy;
 
+/// Complete configuration for a layer-shell surface
+///
+/// Contains all positioning, sizing, and behavioral properties for a surface.
+/// Use with `ShellConfig` for declarative configuration or build via `ShellBuilder`.
 #[derive(Debug, Clone)]
 pub struct SurfaceConfig {
     pub dimensions: SurfaceDimension,

crates/domain/src/dimensions.rs

@@ -1,5 +1,6 @@
 use crate::errors::DomainError;
 
+/// Size in logical pixels, independent of display scaling
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct LogicalSize {
     width: f32,
@@ -65,6 +66,7 @@ impl Default for LogicalSize {
     }
 }
 
+/// Size in physical device pixels
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct PhysicalSize {
     width: u32,
@@ -109,6 +111,7 @@ impl Default for PhysicalSize {
     }
 }
 
+/// Display scaling factor for converting between logical and physical pixels
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct ScaleFactor(f32);
 
@@ -182,6 +185,7 @@ impl TryFrom<f32> for ScaleFactor {
     }
 }
 
+/// Position in logical pixels, independent of display scaling
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct LogicalPosition {
     x: f32,

crates/domain/src/value_objects/anchor_strategy.rs

@@ -1,11 +1,19 @@
+/// Strategy for calculating popup position relative to an anchor rectangle
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum AnchorStrategy {
+    /// Center popup horizontally below the anchor
     CenterBottom,
+    /// Center popup horizontally above the anchor
     CenterTop,
+    /// Position popup at anchor's bottom-left
     LeftBottom,
+    /// Position popup at anchor's bottom-right
     RightBottom,
+    /// Position popup at anchor's top-left
     LeftTop,
+    /// Position popup at anchor's top-right
     RightTop,
+    /// Position popup at cursor coordinates
     Cursor,
 }
 

crates/domain/src/value_objects/dimensions.rs

@@ -1,3 +1,6 @@
+/// Width and height of a layer surface in pixels
+///
+/// Use 0 for either dimension to let the surface stretch along that axis based on anchor edges.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct SurfaceDimension {
     width: u32,

crates/domain/src/value_objects/handle.rs

@@ -38,6 +38,10 @@ pub struct Popup;
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Surface;
 
+/// Type-safe unique identifier for runtime resources
+///
+/// Used as `OutputHandle`, `PopupHandle`, or `SurfaceHandle` to identify
+/// specific instances of those resources.
 pub struct Handle<T> {
     id: HandleId,
     _marker: PhantomData<T>,
@@ -111,6 +115,9 @@ impl Handle<Popup> {
     }
 }
 
+/// Unique identifier for an output (monitor)
 pub type OutputHandle = Handle<Output>;
+/// Unique identifier for a popup window
 pub type PopupHandle = Handle<Popup>;
+/// Unique identifier for a layer surface
 pub type SurfaceHandle = Handle<Surface>;

crates/domain/src/value_objects/keyboard_interactivity.rs

@@ -1,7 +1,11 @@
+/// Controls how a surface receives keyboard input
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum KeyboardInteractivity {
+    /// Surface does not receive keyboard events
     None,
+    /// Surface always receives keyboard focus
     Exclusive,
+    /// Surface receives focus when clicked (default)
     OnDemand,
 }
 

crates/domain/src/value_objects/layer.rs

@@ -1,8 +1,16 @@
+/// Vertical stacking layer for layer-shell surfaces
+///
+/// Determines which layer a surface appears in, affecting visibility and stacking order.
+/// Defaults to `Top` for typical panels and bars.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Layer {
+    /// Lowest layer, typically for wallpapers
     Background,
+    /// Below normal windows
     Bottom,
+    /// Above normal windows, default for bars/panels
     Top,
+    /// Highest layer, above all other content
     Overlay,
 }
 

crates/domain/src/value_objects/margins.rs

@@ -1,3 +1,4 @@
+/// Spacing margins around a surface in pixels
 #[derive(Debug, Clone, Copy, Default)]
 pub struct Margins {
     pub top: i32,

crates/domain/src/value_objects/output_info.rs

@@ -1,5 +1,6 @@
 use crate::value_objects::output_handle::OutputHandle;
 
+/// Runtime information about a connected output (monitor)
 #[derive(Debug, Clone, PartialEq)]
 pub struct OutputInfo {
     handle: OutputHandle,
@@ -10,6 +11,7 @@ pub struct OutputInfo {
     is_primary: bool,
 }
 
+/// Physical geometry and properties of an output
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OutputGeometry {
     pub x: i32,

crates/domain/src/value_objects/output_policy.rs

@@ -4,10 +4,14 @@ use std::rc::Rc;
 
 type OutputFilter = Rc<dyn Fn(&OutputInfo) -> bool>;
 
+/// Determines which outputs (monitors) should display the surface
 #[derive(Clone)]
 pub enum OutputPolicy {
+    /// Display surface on all connected outputs (default)
     AllOutputs,
+    /// Display surface only on the primary output
     PrimaryOnly,
+    /// Custom filter function to determine output eligibility
     Custom(OutputFilter),
 }
 

crates/domain/src/value_objects/popup_positioning_mode.rs

@@ -1,13 +1,25 @@
+/// Alignment mode for popup positioning
+///
+/// Determines how a popup is aligned relative to its placement point.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum PopupPositioningMode {
+    /// Align popup's top-left corner to placement point
     TopLeft,
+    /// Center popup horizontally at placement point, top edge aligned
     TopCenter,
+    /// Align popup's top-right corner to placement point
     TopRight,
+    /// Center popup vertically at placement point, left edge aligned
     CenterLeft,
+    /// Center popup both horizontally and vertically at placement point
     Center,
+    /// Center popup vertically at placement point, right edge aligned
     CenterRight,
+    /// Align popup's bottom-left corner to placement point
     BottomLeft,
+    /// Center popup horizontally at placement point, bottom edge aligned
     BottomCenter,
+    /// Align popup's bottom-right corner to placement point
     BottomRight,
 }
 

crates/domain/src/value_objects/popup_request.rs

@@ -3,6 +3,9 @@
 pub use super::handle::PopupHandle;
 use super::popup_positioning_mode::PopupPositioningMode;
 
+/// Configuration for showing a popup window
+///
+/// Use `PopupRequest::builder()` to construct with fluent API.
 #[derive(Debug, Clone)]
 pub struct PopupRequest {
     pub component: String,
@@ -39,10 +42,14 @@ impl PopupRequest {
     }
 }
 
+/// Where to position a popup relative to the surface
 #[derive(Debug, Clone, Copy)]
 pub enum PopupPlacement {
+    /// At absolute logical position
     AtPosition { x: f32, y: f32 },
+    /// At current cursor position
     AtCursor,
+    /// Relative to a logical rectangle
     AtRect { x: f32, y: f32, w: f32, h: f32 },
 }
 
@@ -71,9 +78,12 @@ impl PopupPlacement {
     }
 }
 
+/// How to size a popup window
 #[derive(Debug, Clone, Copy)]
 pub enum PopupSize {
+    /// Fixed width and height in logical pixels
     Fixed { w: f32, h: f32 },
+    /// Size automatically based on content
     Content,
 }
 

crates/domain/src/value_objects/ui_source.rs

@@ -1,8 +1,13 @@
 use std::path::PathBuf;
 
+/// Source for UI definition at domain level
+///
+/// Lower-level alternative to `CompiledUiSource`. Typically used internally.
 #[derive(Debug, Clone)]
 pub enum UiSource {
+    /// Load from a file path
     File(PathBuf),
+    /// Parse from source code string
     Source(String),
 }