Add documentation

Author: ihamadfuad

Sources/DynamicJSON/Utilities.swift

@@ -8,6 +8,21 @@
 import Foundation
 
 extension String {
+    /// Normalizes a key string into lowercase snake_case format.
+    ///
+    /// This helps unify access to JSON keys that may use various formats such as:
+    /// - camelCase
+    /// - PascalCase
+    /// - snake_case
+    /// - kebab-case
+    /// - Spaced strings ("Feature Toggle")
+    ///
+    /// For example:
+    /// - "betaFeatureX" -> "beta_feature_x"
+    /// - "BETA-FEATURE-X" -> "beta_feature_x"
+    /// - "Feature Toggle" -> "feature_toggle"
+    ///
+    /// Returns: A normalized version of the string for consistent lookup.
     func normalizedKey() -> String {
         let pattern = #"(?<=[a-z0-9])(?=[A-Z])|[_\-\s]+"#
         let regex = try! NSRegularExpression(pattern: pattern, options: [])
@@ -21,6 +36,15 @@ extension String {
             .joined(separator: "_")
     }
 
+    /// Calculates the Levenshtein distance between two strings.
+    ///
+    /// The Levenshtein distance is a measure of how many single-character edits
+    /// (insertions, deletions, or substitutions) are required to change one word into another.
+    ///
+    /// This is useful for implementing fuzzy string matching.
+    ///
+    /// - Parameter target: The string to compare against.
+    /// - Returns: The number of edits needed to match the target.
     func levenshteinDistance(to target: String) -> Int {
         let source = Array(self)
         let target = Array(target)
@@ -47,6 +71,17 @@ extension String {
 }
 
 extension Dictionary where Key == String, Value == DynamicJSON {
+    /// Attempts to find the best-matching key in the dictionary for a given lookup key.
+    ///
+    /// Matching is performed in the following order:
+    /// 1. Exact match (after normalization)
+    /// 2. Partial containment (normalized query is a substring of a key)
+    /// 3. Fuzzy match using Levenshtein distance (within a threshold)
+    ///
+    /// - Parameters:
+    ///   - key: The original key string provided for lookup.
+    ///   - logMatch: A closure used to report fallback key matches for debugging.
+    /// - Returns: The best matching `DynamicJSON` value, or `nil` if no reasonable match found.
     func fuzzyMatch(for key: String, logMatch: (_ original: String, _ matched: String) -> Void) -> DynamicJSON? {
         let normalized = key.normalizedKey()