Merge branch 'develop'

.editorconfig

@@ -0,0 +1,8 @@
+[*]
+indent_style = space
+indent_size = 2
+tab_width = 8
+max_line_length = 80
+trim_trailing_whitespace = false
+end_of_line = lf
+insert_final_newline = true

README.md

@@ -28,7 +28,7 @@ declarative DSL to setup MacroExpress routes.
 
 The Macro [Examples](https://github.com/Macro-swift/Examples) package 
 contains a few examples which all can run straight from the source as
-swift-sh scripts.
+[swift-sh](https://github.com/mxcl/swift-sh) scripts.
 
 ```swift
 #!/usr/bin/swift sh
@@ -80,5 +80,10 @@ app.listen(1337)
 We like feedback, GitHub stars, cool contract work, 
 presumably any form of praise you can think of.
 
-There is a `#microexpress` channel on the 
-[Noze.io Slack](http://slack.noze.io/). Feel free to join!
+**Want to support my work**?
+Buy an app:
+[Code for SQLite3](https://apps.apple.com/us/app/code-for-sqlite3/id1638111010),
+[Past for iChat](https://apps.apple.com/us/app/past-for-ichat/id1554897185),
+[SVG Shaper](https://apps.apple.com/us/app/svg-shaper-for-swiftui/id1566140414),
+[HMScriptEditor](https://apps.apple.com/us/app/hmscripteditor/id1483239744).
+You don't have to use it! 😀

Sources/dotenv/dotenv.swift

@@ -3,7 +3,7 @@
 //  MacroExpress
 //
 //  Created by Helge Heß on 02.07.20.
-//  Copyright © 2020 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2020-2024 ZeeZide GmbH. All rights reserved.
 //
 
 #if os(Linux)
@@ -17,13 +17,25 @@ import func MacroCore.__dirname
 import func fs.accessSync
 import let  fs.R_OK
 
+/**
+ * How to use:
+ *
+ * ```swift
+ * import dotenv
+ *
+ * dotenv.config()
+ * ```
+ *
+ * This reads the `.env` file (located using `__dirname`),
+ * and adds the contents to the environment of the running process.
+ */
 public enum dotenv {}
 
 public extension dotenv {
 
   #if swift(>=5.3) // oh this mess
   /**
-   * Read the .env config file, apply it to the environment, and return the
+   * Read the .env config file, apply it on the environment, and return the
    * parsed values.
    *
    * Important: Remember to call this as early as possible, otherwise Foundation

Sources/express/Express.swift

@@ -149,20 +149,61 @@ open class Express: SettingsHolder, MountableMiddlewareObject, MiddlewareObject,
 
   // MARK: - SettingsHolder
 
-  public func set(_ key: String, _ value: Any?) {
+  /**
+   * Sets or removes a configuration key in the settings store.
+   *
+   * Example:
+   * ```swift
+   * app.set("view engine", "html")
+   *    .set("views", __dirname() + "/views")
+   * ```
+   *
+   * - Parameters:
+   *   - key:   The name of the key, e.g. "view engine"
+   *   - value: The associated value, if `nil` is passed in, the value is
+   *            removed from the store.
+   * - Returns: `self` for chaining.
+   */
+  @discardableResult
+  public func set(_ key: String, _ value: Any?) -> Self {
     if let v = value { settingsStore[key] = v }
     else             { settingsStore.removeValue(forKey: key) }
+    return self
   }
+
+  /**
+   * Returns the value of a configuration key from the settings store.
+   *
+   * Example:
+   * ```swift
+   * let engine = app.get("view engine")
+   * ```
+   *
+   * - Parameters:
+   *   - key:   The name of the key, e.g. "view engine"
+   * - Returns: The value in the store, or `nil` if missing.
+   */
   public func get(_ key: String) -> Any? {
     return settingsStore[key]
   }
 
+
   // MARK: - Engines
 
-  var engines = [ String : ExpressEngine]()
+  var engines = [ String : ExpressEngine ]()
 
-  public func engine(_ key: String, _ engine: @escaping ExpressEngine) {
+  /**
+   * Sets an engine implementation.
+   *
+   * Example:
+   * ```swift
+   * app.engine("mustache", mustacheExpress)
+   * ```
+   */
+  @discardableResult
+  public func engine(_ key: String, _ engine: @escaping ExpressEngine) -> Self {
     engines[key] = engine
+    return self
   }
 
 

Sources/express/Settings.swift

@@ -7,31 +7,89 @@
 //
 
 /**
- * Just a special kind of dictionary. The `Express` application class is
+ * Just a special kind of dictionary. The ``Express`` application class is
  * currently the sole example.
  *
  * Examples:
+ * ```swift
+ * app.set("env", "production")
+ * app.enable("x-powered-by")
  *
- *     app.set("env", "production")
- *     app.enable("x-powered-by")
- *
- *     let env = app.settings.env
+ * let env = app.settings.env
+ * ```
  */
 public protocol SettingsHolder {
 
-  func set(_ key: String, _ value: Any?)
+  /**
+   * Sets or removes a configuration key in the settings store.
+   *
+   * Example:
+   * ```swift
+   * app.set("view engine", "html")
+   *    .set("views", __dirname() + "/views")
+   *    .enable("x-powered-by")
+   * ```
+   *
+   * - Parameters:
+   *   - key:   The name of the key, e.g. "view engine"
+   *   - value: The associated value, if `nil` is passed in, the value is
+   *            removed from the store.
+   * - Returns: `self` for chaining.
+   */
+  @discardableResult
+  func set(_ key: String, _ value: Any?) -> Self
+
+  /**
+   * Returns the value of a configuration key from the settings store.
+   *
+   * Example:
+   * ```swift
+   * let engine = app.get("view engine")
+   * ```
+   *
+   * - Parameters:
+   *   - key:   The name of the key, e.g. "view engine"
+   * - Returns: The value in the store, or `nil` if missing.
+   */
   func get(_ key: String) -> Any?
 }
 
 public extension SettingsHolder {
 
+  /**
+   * Set configuration key in the settings store to `true`.
+   *
+   * Example:
+   * ```swift
+   * app.enable("x-powered-by")
+   * ```
+   *
+   * - Parameters:
+   *   - key:   The name of the bool key, e.g. "view engine"
+   * - Returns: `self` for chaining.
+   */
   @inlinable
-  func enable(_ key: String) {
-    set(key, true)
+  @discardableResult
+  func enable(_ key: String) -> Self {
+    return set(key, true)
   }
+
+  /**
+   * Set configuration key in the settings store to `false`.
+   *
+   * Example:
+   * ```swift
+   * app.disable("x-powered-by")
+   * ```
+   *
+   * - Parameters:
+   *   - key:   The name of the bool key, e.g. "view engine"
+   * - Returns: `self` for chaining.
+   */
   @inlinable
-  func disable(_ key: String) {
-    set(key, false)
+  @discardableResult
+  func disable(_ key: String) -> Self {
+    return set(key, false)
   }
 
   @inlinable