docs(examples): create a readme with details

11 files changed, 148 insertions, 10 deletions

diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..f75a4a5
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,138 @@
+# Examples
+
+## [Async Stateful Module](./async_stateful_module.rs)
+
+`cargo run --example async_stateful_module --features response-macros`
+
+Demonstrates use of the `AsyncModule` trait by implementing the module
+`Clicker` which tracks the global number of visits to the capsule.
+
+This can easily be adapted to contain a hashmap of routes which are individually
+tracked for clicks.
+
+## [Async](./async.rs)
+
+`cargo run --example async --features response-macros`
+
+Demonstrates use of async routes through an async response macro and
+implementing a click tracker using a shared variable through an thread-safe,
+async mutex.
+
+## [Binary](./binary.rs)
+
+`cargo run --example binary --features response-macros`
+
+Demonstrates the binary response functionality by using both manual
+and automatic mime resolution (`--features auto-deduce-mime`).
+
+## [Callbacks](./callbacks.rs)
+
+`cargo run --example callbacks`
+
+Demonstrates use of the pre and post-route callback handlers.
+
+## [Certificate](./certificate.rs)
+
+`cargo run --example certificate --features response-macros`
+
+Demonstrate the various certificate related responses as well as
+reading the client certificate to give conditional access.
+
+## [Default Logger](./default_logger.rs)
+
+`cargo run --example default_logger --features logger,response-macros`
+
+A simple example showing the use of the default default logger implementation.
+
+## [Empty](./empty.rs)
+
+`cargo run --example empty`
+
+An empty example which starts up a server but has no mounted routes.
+
+## [Error Handler](./error_handler.rs)
+
+`cargo run --example error_handler`
+
+Creates an intentional error within a route, invoking the error handler.
+
+## [Fix Path](./fix_path.rs)
+
+`cargo run --example fix_path --features response-macros`
+
+A simple example which demonstrates use of the path fixer that attempts to resolve the closest match of a route when an invalid route is visited.
+
+This feature is limited to simple resolution patches such as resolving
+trailing and missing trailing slashes. If your capsule requires a more sophisticated path fixer, please use any of the provided mechanisms to do so before your routes execute.
+
+## [Input](./input.rs)
+
+`cargo run --example input`
+
+Demonstrates how to accept and inspect both standard and sensitive input.
+
+## [MIME](./mime.rs)
+
+`cargo run --example mime`
+
+Demonstrate how to modify the MIME of a response before use.
+
+## [Parameters](./parameters.rs)
+
+`cargo run --example parameters --features response-macros`
+
+Demonstrate the use of route parameters (not URL queries).
+
+## [Partial](./partial.rs)
+
+`cargo run --example partial`
+
+Demonstrates use of appending headers and footers to routes, globally.
+
+If you would like to conditionally append headers and footers based on route, please look into using a templating framework.
+
+## [Query](./query.rs)
+
+`cargo run --example input --features response-macros`
+
+Demonstrates the inspection of URL queries parameters.
+
+## [Responses](./responses.rs)
+
+`cargo run --example responses --features response-macros`
+
+Demonstrates the use of a wide variety of responses, additionally exposing the flexibility of response bodies types.
+
+## [Simple `async-std`](./simple_async_std.rs)
+
+`cargo run --example simple_async_std --features async-std`
+
+Demonstrates how to explicitly specify Windmark to use the [`async-std`](https://github.com/async-rs/async-std) runtime.
+
+If the `async-std` feature is NOT enabled, Windmark will default to using Tokio as the async runtime.
+
+## [Simple Tokio](./simple_tokio.rs)
+
+`cargo run --example simple_async_std --features async-std`
+
+Demonstrates how to explicitly specify Windmark to use the [Tokio](https://github.com/tokio-rs/tokio) runtime.
+
+## [Stateful Module](./stateful_module.rs)
+
+`cargo run --example stateful_module --features response-macros`
+
+Demonstrates use of `Module`s by implementing a click tracker
+
+Identical in functionality to the Async Stateful Module example, just not asynchronous.
+
+## [Stateless Module](./stateless_module.rs)
+
+`cargo run --example stateless_module`
+
+Demonstrates use of a stateless module.
+
+Unlike a `Module`, a stateless module is not encapsulated into a `struct`, but is a simple function which is used to perform operations.
+
+Stateless modules are able to emulate stateful modules employing `static` variables. The earliest Windmark modules (add-ons) were made this way.
+
+The only requirement of a module is to implement the signature of a stateless module: `FnMut(&mut Router) -> ()`.
diff --git a/examples/async.rs b/examples/async.rs
index d11be86..2c32220 100644
--- a/examples/async.rs
+++ b/examples/async.rs
@@ -15,7 +15,7 @@
 // Copyright (C) 2022-2023 Fuwn <[email protected]>
 // SPDX-License-Identifier: GPL-3.0-only
 
-//! `cargo run --example async`
+//! `cargo run --example async --features response-macros`
 
 #[windmark::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
diff --git a/examples/async_stateful_module.rs b/examples/async_stateful_module.rs
index 09b6cb1..3a2cb0a 100644
--- a/examples/async_stateful_module.rs
+++ b/examples/async_stateful_module.rs
@@ -15,7 +15,7 @@
 // Copyright (C) 2022-2023 Fuwn <[email protected]>
 // SPDX-License-Identifier: GPL-3.0-only
 
-//! `cargo run --example async_stateful_module`
+//! `cargo run --example async_stateful_module --features response-macros`
 
 use std::sync::{Arc, Mutex};
 
diff --git a/examples/binary.rs b/examples/binary.rs
index 3255157..2fbb652 100644
--- a/examples/binary.rs
+++ b/examples/binary.rs
@@ -15,7 +15,7 @@
 // Copyright (C) 2022-2023 Fuwn <[email protected]>
 // SPDX-License-Identifier: GPL-3.0-only
 
-//! `cargo run --example binary`
+//! `cargo run --example binary --features response-macros`
 //!
 //! Optionally, you can run this example with the `auto-deduce-mime` feature
 //! enabled.
diff --git a/examples/certificate.rs b/examples/certificate.rs
index 7c3d3a5..f93d724 100644
--- a/examples/certificate.rs
+++ b/examples/certificate.rs
@@ -15,7 +15,7 @@
 // Copyright (C) 2022-2023 Fuwn <[email protected]>
 // SPDX-License-Identifier: GPL-3.0-only
 
-//! `cargo run --example certificate`
+//! `cargo run --example certificate --features response-macros`
 
 use windmark::Response;
 
diff --git a/examples/default_logger.rs b/examples/default_logger.rs
index 17cd559..994bb6e 100644
--- a/examples/default_logger.rs
+++ b/examples/default_logger.rs
@@ -15,7 +15,7 @@
 // Copyright (C) 2022-2023 Fuwn <[email protected]>
 // SPDX-License-Identifier: GPL-3.0-only
 
-//! `cargo run --example default_logger --features logger`
+//! `cargo run --example default_logger --features logger,response-macros`
 
 #[windmark::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
diff --git a/examples/fix_path.rs b/examples/fix_path.rs
index 449f953..1b64602 100644
--- a/examples/fix_path.rs
+++ b/examples/fix_path.rs
@@ -15,7 +15,7 @@
 // Copyright (C) 2022-2023 Fuwn <[email protected]>
 // SPDX-License-Identifier: GPL-3.0-only
 
-//! `cargo run --example fix_path`
+//! `cargo run --example fix_path --features response-macros`
 
 #[windmark::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
diff --git a/examples/parameters.rs b/examples/parameters.rs
index 9d5335b..e329e09 100644
--- a/examples/parameters.rs
+++ b/examples/parameters.rs
@@ -15,7 +15,7 @@
 // Copyright (C) 2022-2023 Fuwn <[email protected]>
 // SPDX-License-Identifier: GPL-3.0-only
 
-//! `cargo run --example parameters`
+//! `cargo run --example parameters --features response-macros`
 
 use windmark::success;
 
diff --git a/examples/query.rs b/examples/query.rs
index d2c51d4..38fc295 100644
--- a/examples/query.rs
+++ b/examples/query.rs
@@ -15,7 +15,7 @@
 // Copyright (C) 2022-2023 Fuwn <[email protected]>
 // SPDX-License-Identifier: GPL-3.0-only
 
-//! `cargo run --example input`
+//! `cargo run --example input --features response-macros`
 
 #[windmark::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
diff --git a/examples/responses.rs b/examples/responses.rs
index c5d19f8..c1bd533 100644
--- a/examples/responses.rs
+++ b/examples/responses.rs
@@ -15,7 +15,7 @@
 // Copyright (C) 2022-2023 Fuwn <[email protected]>
 // SPDX-License-Identifier: GPL-3.0-only
 
-//! `cargo run --example responses`
+//! `cargo run --example responses --features response-macros`
 
 use windmark::success;
 
diff --git a/examples/stateful_module.rs b/examples/stateful_module.rs
index df13206..4347716 100644
--- a/examples/stateful_module.rs
+++ b/examples/stateful_module.rs
@@ -15,7 +15,7 @@
 // Copyright (C) 2022-2023 Fuwn <[email protected]>
 // SPDX-License-Identifier: GPL-3.0-only
 
-//! `cargo run --example stateful_module`
+//! `cargo run --example stateful_module --features response-macros`
 
 use windmark::{context::HookContext, Router};