Add docc documentation

.swiftlint.yml

@@ -3,6 +3,7 @@ disabled_rules:
   - redundant_optional_initialization
 
 opt_in_rules:
+  - missing_docs
 
 included:
 

Package.resolved

@@ -0,0 +1,25 @@
+{
+  "object": {
+    "pins": [
+      {
+        "package": "SwiftDocCPlugin",
+        "repositoryURL": "https://github.com/apple/swift-docc-plugin",
+        "state": {
+          "branch": null,
+          "revision": "26ac5758409154cc448d7ab82389c520fa8a8247",
+          "version": "1.3.0"
+        }
+      },
+      {
+        "package": "SymbolKit",
+        "repositoryURL": "https://github.com/apple/swift-docc-symbolkit",
+        "state": {
+          "branch": null,
+          "revision": "b45d1f2ed151d057b54504d653e0da5552844e34",
+          "version": "1.0.0"
+        }
+      }
+    ]
+  },
+  "version": 1
+}

Package.swift

@@ -10,6 +10,7 @@ let package = Package(
             targets: ["ScreamURITemplate"]),
     ],
     dependencies: [
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
     ],
     targets: [
         .target(

Sources/ScreamURITemplate/Internal/CharacterSets.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Sources/ScreamURITemplate/Internal/Components.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Sources/ScreamURITemplate/Internal/ExpansionConfiguration.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Sources/ScreamURITemplate/Internal/ExpressionOperator.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Sources/ScreamURITemplate/Internal/Scanner.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Sources/ScreamURITemplate/Internal/ValueFormatting.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Sources/ScreamURITemplate/Internal/VariableSpec.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Sources/ScreamURITemplate/URITemplate.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
@@ -14,15 +14,23 @@
 
 import Foundation
 
+/// An [RFC6570](https://tools.ietf.org/html/rfc6570) URI Template
 public struct URITemplate {
+    /// An error that may be thrown when parsing or processing a template
     public enum Error: Swift.Error {
+        /// Represents an error parsing a string into a URI Template
         case malformedTemplate(position: String.Index, reason: String)
+        /// Represents an error processing a template
         case expansionFailure(position: String.Index, reason: String)
     }
 
     private let string: String
     private let components: [Component]
 
+    /// Initializes a URITemplate from a string
+    /// - Parameter string: the string representation of the URI Template
+    ///
+    /// - Throws: `URITemplate.Error.malformedTemplate` if the string is not a valid URI Template
     public init(string: String) throws {
         var components: [Component] = []
         var scanner = Scanner(string: string)
@@ -33,6 +41,12 @@ public struct URITemplate {
         self.components = components
     }
 
+    /// Process a URI Template specifying variables with a ``TypedVariableProvider``
+    /// - Parameter variables: A ``TypedVariableProvider`` that can provide values for the template variables
+    ///
+    /// - Returns: The result of processing the template
+    ///
+    /// - Throws: `URITemplate.Error.expansionFailure` if an error occurs processing the template
     public func process(variables: TypedVariableProvider) throws -> String {
         var result = ""
         for component in components {
@@ -41,6 +55,15 @@ public struct URITemplate {
         return result
     }
 
+    /// Process a URI Template specifying variables with a ``VariableProvider``
+    ///
+    /// This method allows for specifying variables in a more ergonomic manner compared to using ``TypedVariableValue`` directly
+    ///
+    /// - Parameter variables: A ``VariableProvider`` that can provide values for the template variables
+    ///
+    /// - Returns: The result of processing the template
+    ///
+    /// - Throws: `URITemplate.Error.expansionFailure` if an error occurs processing the template
     public func process(variables: VariableProvider) throws -> String {
         struct TypedVariableProviderWrapper: TypedVariableProvider {
             let variables: VariableProvider
@@ -53,10 +76,20 @@ public struct URITemplate {
         return try process(variables: TypedVariableProviderWrapper(variables: variables))
     }
 
+    /// Process a URI Template where the variable values are all of type string
+    ///
+    /// This method is an override allowing for the special case of string-only variables without needing to typecast
+    ///
+    /// - Parameter variables: A [String: String] dictionary representing the variables
+    ///
+    /// - Returns: The result of processing the template
+    ///
+    /// - Throws: `URITemplate.Error.expansionFailure` if an error occurs processing the template
     public func process(variables: [String: String]) throws -> String {
         return try process(variables: variables as VariableDictionary)
     }
 
+    /// An array of all variable names used in the template
     public var variableNames: [String] {
         return components.flatMap { component in
             return component.variableNames

Sources/ScreamURITemplate/VariableProvider.swift

@@ -1,3 +1,4 @@
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
@@ -13,22 +14,48 @@
 
 import Foundation
 
+/// A type that provides variable values to use in template processing
+///
+/// This type provides values using ``VariableValue`` which allows for an ergonomic way to provide values.
 public protocol VariableProvider {
+    /// Get the ``VariableValue`` for a given variable
+    ///
+    /// - Parameters:
+    ///   - _: the name of the variable
+    ///
+    /// - Returns: the ``VariableValue`` for the variable, or `nil` if the variable has no value
     subscript(_: String) -> VariableValue? { get }
 }
 
+/// A type that provides variable values to use in template processing
+///
+/// This type provides values using ``TypedVariableValue``
+///
+/// Consider using ``VariableProvider`` for a more ergonomic way of providing variable values.
 public protocol TypedVariableProvider {
+    /// Get the ``TypedVariableValue`` for a given variable
+    ///
+    /// - Parameters:
+    ///   - _: the name of the variable
+    ///
+    /// - Returns: the ``TypedVariableValue`` for the variable, or `nil` if the variable has no value
     subscript(_: String) -> TypedVariableValue? { get }
 }
 
+/// A typealias for the most simple ``VariableProvider`` implementation: `[String: VariableValue]`
 public typealias VariableDictionary = [String: VariableValue]
 
 extension VariableDictionary: VariableProvider {}
 
+/// A typealias for the most simple ``TypedVariableProvider`` implementation: `[String: TypedVariableValue]`
 public typealias TypedVariableDictionary = [String: TypedVariableValue]
 
 extension TypedVariableDictionary: TypedVariableProvider {}
 
+/// An object that aggregates a `Sequence` of ``VariableProvider`` as a single ``VariableProvider``
+///
+/// This object allows using a prioritised sequence of VariableProvider as a single VariableProvider.
+/// The first VariableProvider in the sequence that provides a value for a given variable name is the value that is returned.
 public struct SequenceVariableProvider: VariableProvider, ExpressibleByArrayLiteral {
     let sequence: any Sequence<VariableProvider>
 

Sources/ScreamURITemplate/VariableValue.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.
@@ -14,21 +14,45 @@
 
 import Foundation
 
+/// The value of a URITemplate variable to use during processing
+///
+/// This type represents the value of a variable, as defined by [RFC6570](https://tools.ietf.org/html/rfc6570), to be used in
+/// template processing.
+///
+/// Variables can be either a string, a list of strings, or an associative array of string key, value pairs.
+///
+/// While you can process a template by providing variable values using this type (via ``TypedVariableProvider``) you may find it
+/// more ergonomic to provide ``VariableValue`` using ``VariableProvider``, or for simple cases simply `[String: String]`
 public enum TypedVariableValue {
+    /// A simple string value
     case string(String)
+    /// An ordered list of strings
     case list([String])
+    /// An associative array of string key, value pairs
+    ///
+    /// Note that the elements are ordered
     case associativeArray([(key: String, value: String)])
 }
 
+/// A protocol enabling ergonomic expression of variable values
+///
+/// Conforming a type to this protocol will enable it to be directly provided as a variable value via ``VariableProvider``
 public protocol VariableValue {
+    /// Converts this value to a TypedVariableValue to be used for template processing
     func asTypedVariableValue() -> TypedVariableValue?
 }
 
+/// A protocol enabling ergonomic expression of simple string variable values
+///
+/// Conforming a type to this protocol will enable it to be directly provided as a variable value, or as an element in a list or
+/// associative array value via ``VariableProvider``
 public protocol StringVariableValue: VariableValue {
+    /// Converts this value to a `String` to be used for template processing
     func asString() -> String
 }
 
 public extension StringVariableValue {
+    /// Converts this value to a TypedVariableValue to be used for template processing
     func asTypedVariableValue() -> TypedVariableValue? {
         .string(asString())
     }
@@ -53,6 +77,7 @@ extension [String: StringVariableValue]: VariableValue {
 }
 
 public extension LosslessStringConvertible {
+    /// Converts this value to a `String` to be used for template processing
     func asString() -> String {
         description
     }

Sources/ScreamURITemplateExample/main.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Tests/ScreamURITemplateTests/JSONValue.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Tests/ScreamURITemplateTests/TestFileTests.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Tests/ScreamURITemplateTests/TestModels.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.

Tests/ScreamURITemplateTests/Tests.swift

@@ -1,4 +1,4 @@
-//   Copyright 2018-2023 Alex Deem
+//   Copyright 2018-2024 Alex Deem
 //
 //   Licensed under the Apache License, Version 2.0 (the "License");
 //   you may not use this file except in compliance with the License.