diff --git a/src/Network/Wai/Handler/WarpTLS/Simple.hs b/src/Network/Wai/Handler/WarpTLS/Simple.hs
--- a/src/Network/Wai/Handler/WarpTLS/Simple.hs
+++ b/src/Network/Wai/Handler/WarpTLS/Simple.hs
@@ -2,15 +2,68 @@
 {-# LANGUAGE StandaloneDeriving #-}
 {-# LANGUAGE TemplateHaskell #-}
 
+{- |
+Simplified TLS configuration for Warp servers with automatic certificate generation
+
+This module provides a simplified interface for running Warp servers with TLS support,
+including automatic self-signed certificate generation for development environments.
+
+The main design goals are:
+
+* __HTTPS by default__: TLS is enabled by default with automatic certificate generation
+* __Zero-configuration development__: Works out of the box for local development
+* __Production-ready__: Supports custom certificates for production deployment
+* __CLI integration__: Provides 'tlsConfigParser' for command-line argument parsing
+
+= Quick Start
+
+@
+import Network.Wai.Handler.WarpTLS.Simple
+import Network.Wai.Handler.Warp qualified as Warp
+
+main :: IO ()
+main = do
+  let settings = Warp.defaultSettings & Warp.setPort 8080
+  startWarpServer settings ".\/state" TLSAuto myWaiApplication
+@
+
+= Certificate Management
+
+The module supports three TLS configurations:
+
+* 'TLSAuto' - Automatically generates self-signed certificates (default)
+* 'TLSExplicit' - Uses user-provided certificate and key files
+* 'TLSDisabled' - Runs HTTP only (must be explicitly requested)
+
+Auto-generated certificates include Subject Alternative Names (SAN) for:
+
+* @localhost@ and the specified hostname
+* Common local network IP ranges (@127.0.0.1@, @192.168.*.*@, @10.*.*.*@, etc.)
+* IPv6 loopback (@::1@)
+
+= CLI Integration
+
+@
+data MyAppConfig = MyAppConfig
+  { port :: Int
+  , tlsConfig :: TLSConfig
+  }
+
+myConfigParser :: Parser MyAppConfig
+myConfigParser = MyAppConfig
+  \<$\> option auto (long \"port\" \<\> value 8080)
+  \<*\> tlsConfigParser
+@
+-}
 module Network.Wai.Handler.WarpTLS.Simple (
-  -- * Type
+  -- * TLS Configuration
   TLSConfig (..),
 
-  -- * Function
+  -- * Server Functions
   tlsConfigResolve,
   startWarpServer,
 
-  -- * CLI parser
+  -- * CLI Integration
   tlsConfigParser,
 ) where
 
@@ -32,7 +85,42 @@
 opensslBin :: FilePath
 opensslBin = $(staticWhich "openssl")
 
--- | TLS configuration with HTTPS enabled by default
+{- | TLS configuration with HTTPS enabled by default
+
+This type represents the three supported TLS modes for the Warp server:
+
+[TLSDisabled] HTTP-only mode. Must be explicitly requested with @--no-https@ flag.
+This is useful for development behind a reverse proxy or when TLS termination
+happens elsewhere.
+
+[TLSAuto] __Default mode__. Automatically generates self-signed certificates for HTTPS.
+Certificates are stored in @\<stateDir\>\/tls\/@ and include SAN entries for local
+development. This provides zero-configuration HTTPS for development environments.
+
+[TLSExplicit] Production mode with user-provided certificates. Requires both
+certificate and private key files specified via @--tls-cert@ and @--tls-key@ flags.
+
+== Examples
+
+Auto-generated certificates (default):
+@
+tlsConfig = TLSAuto
+@
+
+Custom certificates for production:
+@
+tlsSettings <- WarpTLS.tlsSettings "\/path\/to\/cert.pem" "\/path\/to\/key.pem"
+tlsConfig = TLSExplicit tlsSettings
+@
+
+HTTP-only mode:
+@
+tlsConfig = TLSDisabled
+@
+
+The 'Show' instance provides debugging information including certificate details
+for 'TLSExplicit' configurations.
+-}
 data TLSConfig
   = -- | No TLS - run HTTP only (explicit)
     TLSDisabled
@@ -47,7 +135,16 @@
     TLSAuto -> "TLSAuto"
     TLSExplicit tlsSettings -> "TLSExplicit (user-provided certificates): " <> Text.Show.show (WarpTLS.getCertSettings tlsSettings)
 
--- | Parser for TLS configuration with HTTPS enabled by default
+{- | Command-line parser for TLS configuration
+
+Provides @optparse-applicative@ integration with HTTPS enabled by default:
+
+* @--no-https@ - Disable HTTPS
+* @--tls-cert FILE --tls-key FILE@ - Use custom certificates
+* Default - Auto-generate certificates
+
+Both certificate options must be provided together.
+-}
 tlsConfigParser :: Parser TLSConfig
 tlsConfigParser =
   noHttpsMode <|> tlsExplicitMode <|> defaultMode
@@ -75,6 +172,17 @@
     -- Default to auto-generation (HTTPS enabled by default)
     defaultMode = pure TLSAuto
 
+{- | Resolve TLS configuration to WarpTLS settings
+
+Converts a 'TLSConfig' to the appropriate 'WarpTLS.TLSSettings' for the Warp server:
+
+* 'TLSDisabled' → 'Nothing' (HTTP mode)
+* 'TLSAuto' → Auto-generates certificates in @stateDir\/tls\/@
+* 'TLSExplicit' → Uses provided settings
+
+For 'TLSAuto', certificates are generated once and reused on subsequent runs.
+The hostname "localhost" is used for certificate generation.
+-}
 tlsConfigResolve :: FilePath -> TLSConfig -> IO (Maybe WarpTLS.TLSSettings)
 tlsConfigResolve stateDir = \case
   TLSDisabled -> pure Nothing
@@ -242,7 +350,16 @@
 generateCertificates certDir hostArg =
   generateCertificateWithRequest certDir (defaultCertRequest hostArg)
 
--- | Start a Warp server with optional TLS
+{- | Start a Warp server with TLS support
+
+High-level function that combines Warp settings, TLS configuration, and application:
+
+* Resolves the TLS configuration using the state directory
+* Starts HTTP server if TLS is disabled
+* Starts HTTPS server if TLS is enabled
+
+This is the main entry point for applications using this module.
+-}
 startWarpServer :: Warp.Settings -> FilePath -> TLSConfig -> Application -> IO ()
 startWarpServer settings stateDir tlsConfig app =
   tlsConfigResolve stateDir tlsConfig >>= \case
diff --git a/warp-tls-simple.cabal b/warp-tls-simple.cabal
--- a/warp-tls-simple.cabal
+++ b/warp-tls-simple.cabal
@@ -5,7 +5,7 @@
 -- see: https://github.com/sol/hpack
 
 name:           warp-tls-simple
-version: 0.1.0.1
+version: 0.1.0.2
 synopsis:       Simple TLS configuration for Warp
 description:    Simplified TLS setup and certificate generation for Warp servers
 category:       Web