Merge pull request #30 from mattpolzin/abbreviation-audit

Audit codebase for unnecessary abbreviation usage

Sources/OpenAPIKit/CodableVendorExtendable.swift

@@ -8,7 +8,21 @@
 import Foundation
 import AnyCodable
 
-protocol ExtendableCodingKey: CodingKey, Equatable {
+/// A `VendorExtendable` type is a type that supports arbitrary
+/// additions as long as those additions are keyed by strings starting
+/// with "x-" (e.g. "x-customThing").
+public protocol VendorExtendable {
+    typealias VendorExtensions = [String: AnyCodable]
+
+    /// Dictionary of vendor extensions.
+    ///
+    /// These should be of the form:
+    /// `[ "x-extensionKey": <anything>]`
+    /// where the values are anything codable.
+    var vendorExtensions: VendorExtensions { get }
+}
+
+internal protocol ExtendableCodingKey: CodingKey, Equatable {
     /// An array of all keys that are not vendor extensions.
     static var allBuiltinKeys: [Self] { get }
 
@@ -24,34 +38,32 @@ protocol ExtendableCodingKey: CodingKey, Equatable {
 extension ExtendableCodingKey {
     /// Returns a builtin key if possible, but assumes any other
     /// key is an extended key.
-    public static func key(for value: String) -> Self {
+    internal static func key(for value: String) -> Self {
         return Self(stringValue: value) ?? .extendedKey(for: value)
     }
 }
 
-public protocol VendorExtendable {
-    typealias VendorExtensions = [String: AnyCodable]
-
-    /// Dictionary of vendor extensions.
-    ///
-    /// These should be of the form:
-    /// `[ "x-extensionKey": <anything>]`
-    /// where the values are anything codable.
-    var vendorExtensions: VendorExtensions { get }
-}
-
-protocol CodableVendorExtendable: VendorExtendable {
+internal protocol CodableVendorExtendable: VendorExtendable {
     associatedtype CodingKeys: ExtendableCodingKey
 }
 
-enum VendorExtensionDecodingError: Swift.Error {
+internal enum VendorExtensionDecodingError: Swift.Error, CustomStringConvertible {
     case selfIsArrayNotDict
     case foundNonStringKeys
+
+    var description: String {
+        switch self {
+        case .selfIsArrayNotDict:
+            return "Tried to get vendor extensions on a list. Vendor extensions are necessarily keyed and therefore can only be retrieved from hashes."
+        case .foundNonStringKeys:
+            return "Vendor extension keys must be string values."
+        }
+    }
 }
 
 extension CodableVendorExtendable {
 
-    public static func extensions(from decoder: Decoder) throws -> VendorExtensions {
+    internal static func extensions(from decoder: Decoder) throws -> VendorExtensions {
 
         let decoded = try AnyCodable(from: decoder).value
 
@@ -80,7 +92,7 @@ extension CodableVendorExtendable {
         return extensions.mapValues(AnyCodable.init)
     }
 
-    public func encodeExtensions<T: KeyedEncodingContainerProtocol>(to container: inout T) throws where T.Key == Self.CodingKeys {
+    internal func encodeExtensions<T: KeyedEncodingContainerProtocol>(to container: inout T) throws where T.Key == Self.CodingKeys {
         for (key, value) in vendorExtensions {
             let xKey = key.starts(with: "x-") ? key : "x-\(key)"
             try container.encode(value, forKey: .extendedKey(for: xKey))

Sources/OpenAPIKit/Components.swift

@@ -9,7 +9,10 @@ import Foundation
 import OrderedDictionary
 
 extension OpenAPI {
-    /// What the spec calls the "Components Object".
+    /// OpenAPI Spec "Components Object".
+    ///
+    /// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#components-object
+    /// 
     /// This is a place to put reusable components to
     /// be referenced from other parts of the spec.
     public struct Components: Equatable {
@@ -50,7 +53,7 @@ extension OpenAPI {
             securitySchemes: [:]
         )
 
-        var isEmpty: Bool {
+        public var isEmpty: Bool {
             return self == .noComponents
         }
     }
@@ -237,7 +240,7 @@ extension OpenAPI.Components: Decodable {
 }
 
 extension OpenAPI.Components {
-    enum CodingKeys: String, CodingKey {
+    internal enum CodingKeys: String, CodingKey {
         case schemas
         case responses
         case parameters

Sources/OpenAPIKit/Content.swift

@@ -11,6 +11,9 @@ import OrderedDictionary
 import AnyCodable
 
 extension OpenAPI {
+    /// OpenAPI Spec "Media Type Object"
+    /// 
+    /// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#media-type-object
     public struct Content: Equatable, CodableVendorExtendable {
         public var schema: Either<JSONReference<JSONSchema>, JSONSchema>
         public var example: AnyCodable?
@@ -157,9 +160,9 @@ extension OpenAPI.Content: Decodable {
 }
 
 extension OpenAPI.Content {
-    enum CodingKeys: ExtendableCodingKey {
+    internal enum CodingKeys: ExtendableCodingKey {
         case schema
-        case example
+        case example  // `example` and `examples` are mutually exclusive
         case examples // `example` and `examples` are mutually exclusive
         case encoding
         case extended(String)

Sources/OpenAPIKit/ContentEncoding.swift

@@ -6,6 +6,9 @@
 //
 
 extension OpenAPI.Content {
+    /// OpenAPI Spec "Encoding Object"
+    /// 
+    /// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#encoding-object
     public struct Encoding: Equatable {
         public typealias Style = OpenAPI.PathItem.Parameter.Schema.Style
 

Sources/OpenAPIKit/Decoding Errors/DecodingErrorExtensions.swift

@@ -13,8 +13,8 @@ internal extension Swift.DecodingError {
             switch self {
             case .keyNotFound(let key, _):
                 return "\(key.stringValue)"
-            case .typeMismatch(_, let ctx), .valueNotFound(_, let ctx), .dataCorrupted(let ctx):
-                return ctx.codingPath.last?.stringValue
+            case .typeMismatch(_, let context), .valueNotFound(_, let context), .dataCorrupted(let context):
+                return context.codingPath.last?.stringValue
             @unknown default:
                 return nil
             }
@@ -25,8 +25,8 @@ internal extension Swift.DecodingError {
 
     var codingPathWithoutSubject: [CodingKey] {
         switch self {
-        case .keyNotFound(_, let ctx):
-            return ctx.codingPath
+        case .keyNotFound(_, let context):
+            return context.codingPath
         case .typeMismatch(_, let ctx), .valueNotFound(_, let ctx), .dataCorrupted(let ctx):
             return ctx.codingPath.count > 0 ? ctx.codingPath.dropLast() : []
         @unknown default:
@@ -36,8 +36,8 @@ internal extension Swift.DecodingError {
 
     var codingPath: [CodingKey] {
         switch self {
-        case .keyNotFound(_, let ctx), .typeMismatch(_, let ctx), .valueNotFound(_, let ctx), .dataCorrupted(let ctx):
-            return ctx.codingPath
+        case .keyNotFound(_, let context), .typeMismatch(_, let context), .valueNotFound(_, let context), .dataCorrupted(let context):
+            return context.codingPath
         @unknown default:
             return []
         }
@@ -64,23 +64,23 @@ internal extension Swift.DecodingError {
 
     var underlyingError: Swift.Error? {
         switch self {
-        case .typeMismatch(_, let ctx), .valueNotFound(_, let ctx), .keyNotFound(_, let ctx), .dataCorrupted(let ctx):
-            return ctx.underlyingError
+        case .typeMismatch(_, let context), .valueNotFound(_, let context), .keyNotFound(_, let context), .dataCorrupted(let context):
+            return context.underlyingError
         @unknown default:
             return nil
         }
     }
 
     func replacingPath(with codingPath: [CodingKey]) -> Self {
         switch self {
-        case .typeMismatch(let type, let ctx):
-            return .typeMismatch(type, ctx.replacingPath(with: codingPath))
-        case .valueNotFound(let type, let ctx):
-            return .valueNotFound(type, ctx.replacingPath(with: codingPath))
-        case .keyNotFound(let key, let ctx):
-            return .keyNotFound(key, ctx.replacingPath(with: codingPath))
-        case .dataCorrupted(let ctx):
-            return .dataCorrupted(ctx.replacingPath(with: codingPath))
+        case .typeMismatch(let type, let context):
+            return .typeMismatch(type, context.replacingPath(with: codingPath))
+        case .valueNotFound(let type, let context):
+            return .valueNotFound(type, context.replacingPath(with: codingPath))
+        case .keyNotFound(let key, let context):
+            return .keyNotFound(key, context.replacingPath(with: codingPath))
+        case .dataCorrupted(let context):
+            return .dataCorrupted(context.replacingPath(with: codingPath))
         @unknown default:
             return .dataCorrupted(.init(codingPath: codingPath, debugDescription: "unknown error"))
         }

Sources/OpenAPIKit/Decoding Errors/DocumentDecodingError.swift

@@ -15,7 +15,7 @@ extension OpenAPI.Error.Decoding {
         public enum Context {
             case path(Path)
             case inconsistency(InconsistencyError)
-            case generic(Swift.DecodingError)
+            case other(Swift.DecodingError)
         }
     }
 }
@@ -26,7 +26,7 @@ extension OpenAPI.Error.Decoding.Document {
         case .path(let pathError):
             return pathError.subjectName
 
-        case .generic(let decodingError):
+        case .other(let decodingError):
             return decodingError.subjectName
 
         case .inconsistency(let error):
@@ -38,7 +38,7 @@ extension OpenAPI.Error.Decoding.Document {
         switch context {
         case .path(let pathError):
             return pathError.contextString
-        case .generic, .inconsistency:
+        case .other, .inconsistency:
             return relativeCodingPathString.isEmpty
                 ? "in the root Document object"
                 : "in Document\(relativeCodingPathString)"
@@ -49,7 +49,7 @@ extension OpenAPI.Error.Decoding.Document {
         switch context {
         case .path(let pathError):
             return pathError.errorCategory
-        case .generic(let error):
+        case .other(let error):
             return error.errorCategory
         case .inconsistency(let error):
             return .inconsistency(details: error.details)
@@ -58,7 +58,7 @@ extension OpenAPI.Error.Decoding.Document {
 
     internal var relativeCodingPathString: String {
         switch context {
-        case .generic(let decodingError):
+        case .other(let decodingError):
             return decodingError.relativeCodingPathString
         case .inconsistency:
             return ""
@@ -68,7 +68,7 @@ extension OpenAPI.Error.Decoding.Document {
     }
 
     internal init(_ error: DecodingError) {
-        context = .generic(error)
+        context = .other(error)
         codingPath = error.codingPath
     }
 

Sources/OpenAPIKit/Decoding Errors/InconsistencyError.swift

@@ -7,6 +7,9 @@
 
 import Foundation
 
+/// This error type is thrown when a problem _during_ decoding but the
+/// problem is not inherent to the types or structures but rather specific
+/// to the OpenAPI specification rules.
 public struct InconsistencyError: Swift.Error, OpenAPIError {
     public let subjectName: String
     public let details: String

Sources/OpenAPIKit/Decoding Errors/OpenAPIDecodingErrors.swift

@@ -9,6 +9,7 @@ import Foundation
 import Poly
 
 extension OpenAPI.Error {
+    // Just creating a namespace
     public enum Decoding {}
 }
 
@@ -41,8 +42,8 @@ public extension OpenAPIError {
     var localizedDescription: String {
         let subjectString: String = {
             switch errorCategory {
-            case .missing(let kv):
-                switch kv {
+            case .missing(let keyOrValue):
+                switch keyOrValue {
                 case .key:
                     return "Expected to find `\(subjectName)` key"
                 case .value:
@@ -54,8 +55,8 @@ public extension OpenAPIError {
                 } else {
                     return "Expected `\(subjectName)` value"
                 }
-            case .typeMismatch2(possibleTypeName1: let t1, possibleTypeName2: let t2, details: _):
-                return "Found neither a \(t1) nor a \(t2)"
+            case .typeMismatch2(possibleTypeName1: let type1, possibleTypeName2: let type2, details: _):
+                return "Found neither a \(type1) nor a \(type2)"
             case .dataCorrupted:
                 return "Could not parse `\(subjectName)`"
             case .inconsistency(details: _):
@@ -71,8 +72,8 @@ public extension OpenAPIError {
                 return " to be parsable as \(typeName) but it was not"
             case .typeMismatch2(possibleTypeName1: _, possibleTypeName2: _, details: let details):
                 return ". \(details)"
-            case .missing(let kv):
-                switch kv {
+            case .missing(let keyOrValue):
+                switch keyOrValue {
                 case .key:
                     return " but it is missing"
                 case .value:
@@ -92,14 +93,14 @@ public extension OpenAPIError {
 internal extension Swift.Array where Element == CodingKey {
     var stringValue: String {
         return self.map { key in
-            if let intVal = key.intValue {
-                return "[\(intVal)]"
+            if let intValue = key.intValue {
+                return "[\(intValue)]"
             }
-            let strVal = key.stringValue
-            if strVal.contains("/") {
-                return "['\(strVal)']"
+            let strValue = key.stringValue
+            if strValue.contains("/") {
+                return "['\(strValue)']"
             }
-            return ".\(strVal)"
+            return ".\(strValue)"
         }.joined()
     }