More code documentation

Sources/JSONAPI/Document/Document.swift

@@ -7,6 +7,9 @@
 
 import Poly
 
+/// An `EncodableJSONAPIDocument` supports encoding but not decoding.
+/// It is actually more restrictive than `JSONAPIDocument` which supports both
+/// encoding and decoding.
 public protocol EncodableJSONAPIDocument: Equatable, Encodable {
     associatedtype PrimaryResourceBody: JSONAPI.EncodableResourceBody
     associatedtype MetaType: JSONAPI.Meta
@@ -20,6 +23,8 @@ public protocol EncodableJSONAPIDocument: Equatable, Encodable {
     var body: Body { get }
 }
 
+/// A `JSONAPIDocument` supports encoding and decoding of a JSON:API
+/// compliant Document.
 public protocol JSONAPIDocument: EncodableJSONAPIDocument, Decodable where PrimaryResourceBody: JSONAPI.ResourceBody, IncludeType: Decodable {}
 
 /// A JSON API Document represents the entire body

Sources/JSONAPI/Document/Error.swift

@@ -9,6 +9,9 @@ public protocol JSONAPIError: Swift.Error, Equatable, Codable {
 	static var unknown: Self { get }
 }
 
+/// `UnknownJSONAPIError` can actually be used in any sitaution
+/// where you don't know what errors are possible _or_ you just don't
+/// care what errors might show up.
 public enum UnknownJSONAPIError: JSONAPIError {
 	case unknownError
 	

Sources/JSONAPI/Document/ResourceBody.swift

@@ -5,8 +5,14 @@
 //  Created by Mathew Polzin on 11/10/18.
 //
 
+/// This protocol allows for a `SingleResourceBody` to contain a `null`
+/// data object where `ManyResourceBody` cannot (because an empty
+/// array should be used for no results).
 public protocol OptionalEncodablePrimaryResource: Equatable, Encodable {}
 
+/// An `EncodablePrimaryResource` is a `PrimaryResource` that only supports encoding.
+/// This is actually more restrictave than `PrimaryResource`, which supports both encoding and
+/// decoding.
 public protocol EncodablePrimaryResource: OptionalEncodablePrimaryResource {}
 
 /// This protocol allows for `SingleResourceBody` to contain a `null`
@@ -14,7 +20,7 @@ public protocol EncodablePrimaryResource: OptionalEncodablePrimaryResource {}
 /// array should be used for no results).
 public protocol OptionalPrimaryResource: OptionalEncodablePrimaryResource, Decodable {}
 
-/// A PrimaryResource is a type that can be used in the body of a JSON API
+/// A `PrimaryResource` is a type that can be used in the body of a JSON API
 /// document as the primary resource.
 public protocol PrimaryResource: EncodablePrimaryResource, OptionalPrimaryResource {}
 

Sources/JSONAPI/Meta/Meta.swift

@@ -19,6 +19,8 @@ public protocol Meta: Codable, Equatable {
 // nullable.
 extension Optional: Meta where Wrapped: Meta {}
 
+/// Use this type when you want to specify not to encode or decode any metadata
+/// for a type.
 public struct NoMetadata: Meta, CustomStringConvertible {
 	public static var none: NoMetadata { return NoMetadata() }
 

Sources/JSONAPI/Resource/Transformer.swift

@@ -10,12 +10,16 @@ public protocol Transformer {
 	associatedtype From
 	associatedtype To
 
+    /// Turn value of type `From` into a value of type `To` or
+    /// throw an error on failure.
 	static func transform(_ value: From) throws -> To
 }
 
 /// ReversibleTransformers define a function that reverses the transform
 /// operation.
 public protocol ReversibleTransformer: Transformer {
+    /// Turn a value of type `To` into a value of type `From` or
+    /// throw an error on failure.
 	static func reverse(_ value: To) throws -> From
 }
 
@@ -43,7 +47,8 @@ extension Validator {
 	}
 
     /// Validate the given value and then return it if valid.
-    /// throws if invalid.
+    /// throws an erro if invalid.
+    /// - returns: The same value passed in, if it was valid.
 	public static func validate(_ value: To) throws -> To {
 		let _ = try transform(value)
 		return value

Sources/JSONAPI/SparseFields/SparseFieldset.swift

@@ -5,6 +5,9 @@
 //  Created by Mathew Polzin on 8/4/19.
 //
 
+/// A SparseFieldset represents an `Encodable` subset of the fields
+/// a `ResourceObject` would normally encode. Currently, you can
+/// only apply sparse fieldset's to `ResourceObject.Attributes`.
 public struct SparseFieldset<
     Description: JSONAPI.ResourceObjectDescription,
     MetaType: JSONAPI.Meta,
@@ -12,6 +15,7 @@ public struct SparseFieldset<
     EntityRawIdType: JSONAPI.MaybeRawId
 >: EncodablePrimaryResource where Description.Attributes: SparsableAttributes {
 
+    /// The `ResourceObject` type this `SparseFieldset` is capable of modifying.
     public typealias Resource = JSONAPI.ResourceObject<Description, MetaType, LinksType, EntityRawIdType>
 
     public let resourceObject: Resource
@@ -41,6 +45,6 @@ public extension ResourceObject where Description.Attributes: SparsableAttribute
 
 public extension ResourceObject where Description.Attributes: SparsableAttributes {
 
-    /// The Sparse Fieldset type for this `ResourceObject`
+    /// The `SparseFieldset` type for this `ResourceObject`
     typealias SparseType = SparseFieldset<Description, MetaType, LinksType, EntityRawIdType>
 }