From bec29a3fdd59cf779359b141493c7551795eda97 Mon Sep 17 00:00:00 2001
From: drendog <dwenya@dren.dog>
Date: Sun, 16 Nov 2025 18:41:32 +0100
Subject: [PATCH] docs: entrypoint bare docs

---
 src/lib.rs     | 53 ++++++++++++++++++++++++++++++++++++++++++++------
 src/prelude.rs | 21 ++++++++++++++++++--
 2 files changed, 66 insertions(+), 8 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index d6a3479..ef34718 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,19 +1,60 @@
-#![allow(clippy::pub_use)]
+//! layer-shika: A Wayland layer shell library with Slint UI integration
+//!
+//! This crate provides a high-level API for creating Wayland layer shell windows
+//! with Slint-based user interfaces. It's built on a clean architecture with three
+//! internal layers (domain, adapters, composition), but users should only depend on
+//! this root crate.
+//!
+//! # Architecture Note
+//!
+//! layer-shika is internally organized as a Cargo workspace with three implementation
+//! crates:
+//! - `layer-shika-domain`: Core domain models and business logic
+//! - `layer-shika-adapters`: Wayland and rendering implementations
+//! - `layer-shika-composition`: Public API composition layer
+//!
+//! **Users should never import from these internal crates directly.** This allows
+//! the internal architecture to evolve without breaking semver guarantees on the
+//! public API.
+//!
+//! # Quick Start
+//!
+//! ```rust,no_run
+//! use layer_shika::prelude::*;
+//!
+//! let (window, system) = LayerShika::from_file("ui/main.slint", "AppWindow")?
+//!     .with_height(42)?
+//!     .with_anchor(AnchorEdges::top_bar())
+//!     .with_exclusive_zone(42)
+//!     .build()?;
+//!
+//! system.run()?;
+//! # Ok::<(), layer_shika::Error>(())
+//! ```
+//!
+//! # Re-exports
+//!
+//! This crate re-exports commonly needed types from its dependencies:
+//! - [`slint`]: The Slint UI framework (compiled API)
+//! - [`slint_interpreter`]: Runtime Slint component loading
+//! - [`calloop`]: Event loop types for custom event sources
 
-mod composition {
-    pub use layer_shika_composition::*;
-}
+#![allow(clippy::pub_use)]
 
 pub mod prelude;
 
-pub use composition::{
+pub use layer_shika_composition::{
     AnchorEdges, Error, EventLoopHandle, KeyboardInteractivity, Layer, LayerShika, PopupAt,
     PopupHandle, PopupPositioningMode, PopupRequest, PopupSize, PopupWindow, Result, RuntimeState,
     SlintCallbackContract, SlintCallbackNames, WindowingSystem,
 };
 
-pub use composition::{slint, slint_interpreter};
+pub use layer_shika_composition::{slint, slint_interpreter};
 
+/// Re-exported calloop types for event loop integration
+///
+/// These types allow users to register custom event sources on the
+/// layer-shika event loop via [`EventLoopHandle`].
 pub mod calloop {
     pub use layer_shika_composition::calloop::*;
 }
diff --git a/src/prelude.rs b/src/prelude.rs
index bac20fe..89650af 100644
--- a/src/prelude.rs
+++ b/src/prelude.rs
@@ -1,10 +1,27 @@
+//! Prelude module re-exporting all public API types
+//!
+//! Import this module to get access to the most commonly used types:
+//!
+//! ```rust
+//! use layer_shika::prelude::*;
+//! ```
+
 #![allow(clippy::pub_use)]
 
+// Core API types
 pub use crate::{
-    AnchorEdges, Error, KeyboardInteractivity, Layer, LayerShika, PopupAt, PopupPositioningMode,
-    PopupRequest, PopupSize, Result,
+    Error, EventLoopHandle, LayerShika, PopupWindow, Result, RuntimeState,
+    SlintCallbackContract, SlintCallbackNames, WindowingSystem,
 };
 
+// Domain value objects
+pub use crate::{
+    AnchorEdges, KeyboardInteractivity, Layer, PopupAt, PopupHandle, PopupPositioningMode,
+    PopupRequest, PopupSize,
+};
+
+// Event loop types
 pub use crate::calloop;
 
+// UI framework re-exports
 pub use crate::{slint, slint_interpreter};