docs: add more examples on docs comments

crates/composition/src/selection.rs

@@ -93,7 +93,12 @@ impl<'a> Selection<'a> {
 
     /// Registers a callback handler for all matching surfaces
     ///
-    /// Handler receives a `CallbackContext` with surface identity and shell control.
+    /// ```ignore
+    /// shell.select(Surface::named("bar"))
+    ///     .on_callback("clicked", |ctx| {
+    ///         println!("Clicked: {}", ctx.surface_name());
+    ///     });
+    /// ```
     pub fn on_callback<F, R>(&self, callback_name: &str, handler: F) -> &Self
     where
         F: Fn(crate::CallbackContext) -> R + Clone + 'static,
@@ -104,7 +109,17 @@ impl<'a> Selection<'a> {
         self
     }
 
-    /// Registers a callback handler that receives arguments for all matching surfaces
+    /// Registers a callback handler that receives Slint arguments
+    ///
+    /// ```ignore
+    /// // Slint: callback item-clicked(string);
+    /// shell.select(Surface::named("menu"))
+    ///     .on_callback_with_args("item-clicked", |args, ctx| {
+    ///         if let Some(Value::String(item)) = args.get(0) {
+    ///             println!("{} clicked {}", ctx.surface_name(), item);
+    ///         }
+    ///     });
+    /// ```
     pub fn on_callback_with_args<F, R>(&self, callback_name: &str, handler: F) -> &Self
     where
         F: Fn(&[Value], crate::CallbackContext) -> R + Clone + 'static,

crates/composition/src/selector.rs

@@ -14,9 +14,30 @@ pub struct SurfaceInfo {
     pub instance_id: SurfaceInstanceId,
 }
 
-/// Selector for targeting surfaces when setting up callbacks or runtime configuration
+/// Selector for targeting surfaces in callbacks and runtime configuration
 ///
-/// Combine with `.or()`, `.except()`, or `.on()` for complex targeting.
+/// # Examples
+///
+/// ```ignore
+/// // Single surface by name
+/// shell.select(Surface::named("bar"))
+///     .on_callback("clicked", |ctx| { /* ... */ });
+///
+/// // Multiple surfaces
+/// shell.select(Surface::any(["bar", "panel"]))
+///     .set_property("visible", &Value::Bool(true));
+///
+/// // All except one
+/// shell.select(Surface::all().except(Surface::named("hidden")))
+///     .on_callback("update", |ctx| { /* ... */ });
+///
+/// // Custom filter
+/// shell.select(Surface::matching(|info| info.name.starts_with("popup")))
+///     .set_property("layer", &Value::String("overlay".into()));
+///
+/// // Combine with output selector
+/// Surface::named("bar").on(Output::primary())
+/// ```
 #[derive(Clone)]
 pub enum Surface {
     /// Select all surfaces
@@ -50,6 +71,10 @@ impl Surface {
     }
 
     /// Selects surfaces matching a custom predicate
+    ///
+    /// ```ignore
+    /// Surface::matching(|info| info.name.starts_with("widget"))
+    /// ```
     pub fn matching<F>(predicate: F) -> Self
     where
         F: Fn(&SurfaceInfo) -> bool + Send + Sync + 'static,
@@ -58,6 +83,11 @@ impl Surface {
     }
 
     /// Combines this surface selector with an output selector
+    ///
+    /// ```ignore
+    /// Surface::named("bar").on(Output::primary())
+    /// Surface::all().on(Output::named("HDMI-1"))
+    /// ```
     pub fn on(self, output: Output) -> Selector {
         Selector {
             surface: self,
@@ -66,12 +96,20 @@ impl Surface {
     }
 
     /// Inverts the selection to exclude matching surfaces
+    ///
+    /// ```ignore
+    /// Surface::all().except(Surface::named("hidden"))
+    /// ```
     #[must_use]
     pub fn except(self, other: impl Into<Surface>) -> Self {
         Self::Not(Box::new(other.into()))
     }
 
     /// Combines this selector with another using OR logic
+    ///
+    /// ```ignore
+    /// Surface::named("bar").or(Surface::named("panel"))
+    /// ```
     #[must_use]
     pub fn or(self, other: impl Into<Surface>) -> Self {
         match self {
@@ -108,7 +146,23 @@ impl Debug for Surface {
     }
 }
 
-/// Selector for targeting outputs (monitors) in runtime operations
+/// Selector for targeting outputs (monitors)
+///
+/// # Examples
+///
+/// ```ignore
+/// // Primary monitor only
+/// shell.select(Surface::named("bar").on(Output::primary()))
+///     .on_callback("clicked", |ctx| { /* ... */ });
+///
+/// // Specific output by name
+/// shell.select(Output::named("HDMI-1"))
+///     .set_property("scale", &Value::Number(1.5));
+///
+/// // Custom filter
+/// shell.select(Output::matching(|info| info.scale().unwrap_or(1) > 1))
+///     .set_property("enable-hidpi", &Value::Bool(true));
+/// ```
 #[derive(Clone)]
 pub enum Output {
     /// Select all outputs
@@ -156,6 +210,10 @@ impl Output {
     }
 
     /// Selects outputs matching a custom predicate
+    ///
+    /// ```ignore
+    /// Output::matching(|info| info.is_primary())
+    /// ```
     pub fn matching<F>(predicate: F) -> Self
     where
         F: Fn(&OutputInfo) -> bool + Send + Sync + 'static,
@@ -164,12 +222,20 @@ impl Output {
     }
 
     /// Inverts the selection to exclude matching outputs
+    ///
+    /// ```ignore
+    /// Output::all().except(Output::primary())
+    /// ```
     #[must_use]
     pub fn except(self, other: impl Into<Output>) -> Self {
         Self::Not(Box::new(other.into()))
     }
 
     /// Combines this selector with another using OR logic
+    ///
+    /// ```ignore
+    /// Output::named("HDMI-1").or(Output::named("HDMI-2"))
+    /// ```
     #[must_use]
     pub fn or(self, other: impl Into<Output>) -> Self {
         match self {
@@ -220,7 +286,18 @@ impl Debug for Output {
 
 /// Combined surface and output selector for precise targeting
 ///
-/// Targets specific surface instances on specific outputs.
+/// Created by combining `Surface` and `Output` selectors:
+///
+/// ```ignore
+/// Surface::named("bar").on(Output::primary())
+/// ```
+///
+/// Or implicitly from either selector:
+///
+/// ```ignore
+/// shell.select(Surface::named("bar"))  // All outputs
+/// shell.select(Output::primary())      // All surfaces
+/// ```
 #[derive(Clone, Debug)]
 pub struct Selector {
     pub surface: Surface,

crates/composition/src/system.rs

@@ -102,9 +102,12 @@ pub enum ShellCommand {
     Render,
 }
 
-/// Context provided to callback handlers with surface and control information
+/// Context provided to callback handlers
 ///
-/// Provides surface identity, output info, and control handle for runtime operations.
+/// # Callback Signatures
+///
+/// - Basic: `Fn(CallbackContext) -> impl IntoValue`
+/// - With args: `Fn(&[Value], CallbackContext) -> impl IntoValue`
 pub struct CallbackContext {
     instance_id: SurfaceInstanceId,
     surface_name: String,

crates/composition/src/value_conversion.rs

@@ -1,5 +1,6 @@
 use layer_shika_adapters::platform::slint_interpreter::Value;
 
+/// Trait for callback return types
 pub trait IntoValue {
     fn into_value(self) -> Value;
 }