From 86a9345fdd2f85d67d6338045628664663d18346 Mon Sep 17 00:00:00 2001
From: Mathew Polzin <matt.polzin@gmail.com>
Date: Wed, 14 Aug 2019 09:22:06 -0700
Subject: [PATCH] Adding some documentation and making SparseFieldEncoder
 internal because it does not need to be public.

---
 Sources/JSONAPI/Document/Document.swift                |  4 ++++
 Sources/JSONAPI/Document/Includes.swift                | 10 ++++++++++
 Sources/JSONAPI/Document/ResourceBody.swift            |  4 ++++
 Sources/JSONAPI/Resource/Id.swift                      |  3 +++
 Sources/JSONAPI/SparseFields/SparseFieldEncoder.swift  |  4 ++--
 .../SparseFields/SparseFieldEncoderTests.swift         |  2 +-
 6 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/Sources/JSONAPI/Document/Document.swift b/Sources/JSONAPI/Document/Document.swift
index caad138..aedb87a 100644
--- a/Sources/JSONAPI/Document/Document.swift
+++ b/Sources/JSONAPI/Document/Document.swift
@@ -53,7 +53,9 @@ public struct Document<PrimaryResourceBody: JSONAPI.EncodableResourceBody, MetaT
 		case data(Data)
 
 		public struct Data: Equatable {
+            /// The document's Primary Resource object(s)
 			public let primary: PrimaryResourceBody
+            /// The document's included objects
 			public let includes: Includes<Include>
 			public let meta: MetaType
 			public let links: LinksType
@@ -66,6 +68,8 @@ public struct Document<PrimaryResourceBody: JSONAPI.EncodableResourceBody, MetaT
 			}
 		}
 
+        /// `true` if the document represents one or more errors. `false` if the
+        /// document represents JSON:API data and/or metadata.
 		public var isError: Bool {
 			guard case .errors = self else { return false }
 			return true
diff --git a/Sources/JSONAPI/Document/Includes.swift b/Sources/JSONAPI/Document/Includes.swift
index 1608b2d..dc9eb02 100644
--- a/Sources/JSONAPI/Document/Includes.swift
+++ b/Sources/JSONAPI/Document/Includes.swift
@@ -9,6 +9,16 @@ import Poly
 
 public typealias Include = EncodableJSONPoly
 
+/// A structure holding zero or more included Resource Objects.
+/// The resources are accessed by their type using a subscript.
+///
+/// If you have
+///
+/// `let includes: Includes<Include2<Thing1, Thing2>> = ...`
+///
+/// then you can access all `Thing1` included resources with
+///
+/// `let includedThings = includes[Thing1.self]`
 public struct Includes<I: Include>: Encodable, Equatable {
 	public static var none: Includes { return .init(values: []) }
 	
diff --git a/Sources/JSONAPI/Document/ResourceBody.swift b/Sources/JSONAPI/Document/ResourceBody.swift
index 4dbac87..3fdef10 100644
--- a/Sources/JSONAPI/Document/ResourceBody.swift
+++ b/Sources/JSONAPI/Document/ResourceBody.swift
@@ -48,6 +48,9 @@ public func +<R: Appendable>(_ left: R, right: R) -> R {
 	return left.appending(right)
 }
 
+/// A type allowing for a document body containing 1 primary resource.
+/// If the `Entity` specialization is an `Optional` type, the body can contain
+/// 0 or 1 primary resources.
 public struct SingleResourceBody<Entity: JSONAPI.OptionalEncodablePrimaryResource>: EncodableResourceBody {
 	public let value: Entity
 
@@ -56,6 +59,7 @@ public struct SingleResourceBody<Entity: JSONAPI.OptionalEncodablePrimaryResourc
 	}
 }
 
+/// A type allowing for a document body containing 0 or more primary resources.
 public struct ManyResourceBody<Entity: JSONAPI.EncodablePrimaryResource>: EncodableResourceBody, Appendable {
 	public let values: [Entity]
 
diff --git a/Sources/JSONAPI/Resource/Id.swift b/Sources/JSONAPI/Resource/Id.swift
index 7265a18..a375c08 100644
--- a/Sources/JSONAPI/Resource/Id.swift
+++ b/Sources/JSONAPI/Resource/Id.swift
@@ -28,6 +28,9 @@ public protocol CreatableRawIdType: RawIdType {
 
 extension String: RawIdType {}
 
+/// A type that can be used as the `MaybeRawId` for a `ResourceObject` that does not
+/// have an Id (most likely because it was created by a client and the server will be responsible
+/// for assigning it an Id).
 public struct Unidentified: MaybeRawId, CustomStringConvertible {
 	public init() {}
 	
diff --git a/Sources/JSONAPI/SparseFields/SparseFieldEncoder.swift b/Sources/JSONAPI/SparseFields/SparseFieldEncoder.swift
index a377fc9..36a1a95 100644
--- a/Sources/JSONAPI/SparseFields/SparseFieldEncoder.swift
+++ b/Sources/JSONAPI/SparseFields/SparseFieldEncoder.swift
@@ -5,7 +5,7 @@
 //  Created by Mathew Polzin on 8/4/19.
 //
 
-public class SparseFieldEncoder<SparseKey: CodingKey & Equatable>: Encoder {
+class SparseFieldEncoder<SparseKey: CodingKey & Equatable>: Encoder {
     private let wrappedEncoder: Encoder
     private let allowedKeys: [SparseKey]
 
@@ -37,7 +37,7 @@ public class SparseFieldEncoder<SparseKey: CodingKey & Equatable>: Encoder {
     }
 }
 
-public struct SparseFieldKeyedEncodingContainer<Key, SparseKey>: KeyedEncodingContainerProtocol where SparseKey: CodingKey, SparseKey: Equatable, Key: CodingKey {
+struct SparseFieldKeyedEncodingContainer<Key, SparseKey>: KeyedEncodingContainerProtocol where SparseKey: CodingKey, SparseKey: Equatable, Key: CodingKey {
     private var wrappedContainer: KeyedEncodingContainer<Key>
     private let allowedKeys: [SparseKey]
 
diff --git a/Tests/JSONAPITests/SparseFields/SparseFieldEncoderTests.swift b/Tests/JSONAPITests/SparseFields/SparseFieldEncoderTests.swift
index f0abce2..c6192f8 100644
--- a/Tests/JSONAPITests/SparseFields/SparseFieldEncoderTests.swift
+++ b/Tests/JSONAPITests/SparseFields/SparseFieldEncoderTests.swift
@@ -6,7 +6,7 @@
 //
 
 import XCTest
-import JSONAPI
+@testable import JSONAPI
 import Foundation
 
 class SparseFieldEncoderTests: XCTestCase {