From fd81ba977ef4f1ccd9377fdc1fea88b80fa4032d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Helge=20He=C3=9F?= <devteam@zeezide.de>
Date: Sat, 14 Dec 2024 18:02:33 +0100
Subject: [PATCH] The settings engine returns `self` for chaining now

But discardable.
Added comments.
---
 Sources/express/Express.swift  | 47 ++++++++++++++++++--
 Sources/express/Settings.swift | 78 +++++++++++++++++++++++++++++-----
 2 files changed, 112 insertions(+), 13 deletions(-)

diff --git a/Sources/express/Express.swift b/Sources/express/Express.swift
index 1fec3e9..d776440 100644
--- a/Sources/express/Express.swift
+++ b/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
   }
 
   
diff --git a/Sources/express/Settings.swift b/Sources/express/Settings.swift
index 81916d6..23b92cb 100644
--- a/Sources/express/Settings.swift
+++ b/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