Module documentation

src/wisp.gleam

@@ -1,3 +1,50 @@
+/// Wisp! A Gleam web framework.
+///
+/// ## Overview
+///
+/// Wisp is based around two concepts: handlers and middleware.
+///
+/// ### Handlers
+///
+/// A handler is a function that takes a HTTP request and returns a HTTP
+/// response. A handler may also take other arguments, such as a "context" type
+/// defined in your application which may hold other state such as a database
+/// connection or user session.
+///
+/// ```gleam
+/// import wisp.{Request, Response}
+///
+/// pub type Context {
+///   Context(secret: String)
+/// }
+///
+/// pub fn handle_request(request: Request, context: Context) -> Response {
+///   wisp.ok()
+/// }
+/// ```
+///
+/// ### Middleware
+///
+/// A middleware is a function that takes a response returning function as its
+/// last argument, and itself returns a response. As with handlers both
+/// middleware and the functions they take as an argument may take other
+/// arguments.
+///
+/// Middleware can be applied in a handler with Gleam's `use` syntax. Here the
+/// `log_request` middleware is used to log a message for each HTTP request
+/// handled, and the `serve_static` middleware is used to serve static files
+/// such as images and CSS.
+///
+/// ```gleam
+/// import wisp.{Request, Response}
+///
+/// pub fn handle_request(request: Request) -> Response {
+///   use <- wisp.log_request
+///   use <- wisp.serve_static(req, under: "/static", from: "/public")
+///   wisp.ok()
+/// }
+/// ```
+///
 import gleam/string_builder.{StringBuilder}
 import gleam/bit_builder.{BitBuilder}
 import gleam/bit_string
@@ -1082,7 +1129,7 @@ fn join_path(a: String, b: String) -> String {
 ///
 /// ```gleam
 /// fn handle_request(req: Request) -> Response {
-///   use <- wisp.log_request(req)
+///   use <- wisp.serve_static(req, under: "/static", from: "/public")
 ///   // ...
 /// }
 /// ```