diff --git a/.gitignore b/.gitignore
index ea8c4bf..abc5264 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 /target
+examples/target
diff --git a/lib/error.rs b/lib/error.rs
index 1898a1c..4b3a486 100644
--- a/lib/error.rs
+++ b/lib/error.rs
@@ -1,28 +1,48 @@
+//! # Error Module
+//!
+//! Defines `WsgError`, the application-level error type for all WGPU operations.
+//! Every variant maps a specific failure mode to a user-friendly message via `thiserror`.
+
 use thiserror::Error;
 
+/// Application-level errors for the WSG library.
+/// Every variant maps a specific failure mode during GPU initialization or rendering
+/// to a user-friendly message via `thiserror`.
 #[derive(Error, Debug)]
 pub enum WsgError {
-    /// Error from the windowing system (winit)
+    /// The windowing system (winit) failed to create the surface — e.g. no display available.
+    /// Caller: `Context::new()` after `Instance::create_surface()`.
     #[error("Window system error (winit)")]
     WindowSystem,
 
-    /// No suitable graphics adapter found
+    /// No compatible graphics adapter was found for the given surface.
+    /// This can happen if no Vulkan/Metal/DX12 backend is installed or if the integrated GPU
+    /// is not exposed to the process.
+    /// Caller: `Context::new()` after `Instance::request_adapter()`.
     #[error("No graphics adapter found")]
     NoAdapter,
 
-    /// Failed to create a WGPU device
+    /// The requested device could not be obtained from the adapter — typically a driver bug
+    /// or insufficient capabilities.
+    /// Caller: `Context::new()` after `Adapter::request_device()`.
     #[error("Failed to create WGPU device")]
     DeviceCreation,
 
-    /// Shader compilation or creation error
+    /// A shader module failed to compile or link. The inner string holds the compiler output.
+    /// Caller: renderer code that creates shaders via `Device::create_shader_module()`.
     #[error("Shader compilation or creation error: {0}")]
     ShaderError(String),
 
-    /// Internal WGPU error
+    /// An internal WGPU error propagated from a device request failure.
+    /// Automatically converted via `thiserror`'s `#[from]`.
+    /// Caller: `Context::new()` — maps `wgpu::RequestDeviceError` into this variant.
     #[error("Internal WGPU error: {0}")]
     InternalWgpu(#[from] wgpu::RequestDeviceError),
 
-    /// Failed to create the rendering surface
+    /// The OS-level surface could not be created for the given window.
+    /// Common causes: unsupported display server, window closed before surface creation,
+    /// or platform-specific limitation.
+    /// Caller: `Context::new()` after `Instance::create_surface()`.
     #[error("Failed to create rendering surface")]
     SurfaceCreation(wgpu::CreateSurfaceError),
 }