From 1d8ceef317bc33241c25cb62c25a51ac3d788a24 Mon Sep 17 00:00:00 2001
From: Mathew Polzin <matt.polzin@gmail.com>
Date: Sun, 20 Jan 2019 18:52:21 -0800
Subject: [PATCH] Update README, add a bit more code documentation

---
 README.md                                             | 4 ++--
 Sources/JSONAPIArbitrary/Entity+Arbitrary.swift       | 5 +++++
 Sources/JSONAPIArbitrary/Relationship+Arbitrary.swift | 8 ++++++++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 151b691..1b35e86 100644
--- a/README.md
+++ b/README.md
@@ -136,11 +136,11 @@ Note that Playground support for importing non-system Frameworks is still a bit
 	- [x] OpenAPI
 - `links`
 	- [x] Encoding/Decoding
-	- [ ] Arbitrary
+	- [x] Arbitrary
 	- [ ] OpenAPI
 - `meta`
 	- [x] Encoding/Decoding
-	- [ ] Arbitrary
+	- [x] Arbitrary
 	- [ ] OpenAPI
 
 #### Relationship Object
diff --git a/Sources/JSONAPIArbitrary/Entity+Arbitrary.swift b/Sources/JSONAPIArbitrary/Entity+Arbitrary.swift
index b686057..ac22b5f 100644
--- a/Sources/JSONAPIArbitrary/Entity+Arbitrary.swift
+++ b/Sources/JSONAPIArbitrary/Entity+Arbitrary.swift
@@ -32,6 +32,11 @@ extension NoRelationships: Arbitrary {
 	}
 }
 
+// NOTE: Arbitrary conformance for MetaType, LinksType, Description.Attributes,
+// and Description.Relationships must all be provided BY YOU for Entity to
+// gain Arbitrary conformance (with the exception of NoMetadata, NoLinks,
+// NoAttributes, and NoRelationships which all have Arbitrary conformance
+// out of the box).
 extension Entity: Arbitrary where MetaType: Arbitrary, LinksType: Arbitrary, Description.Attributes: Arbitrary, Description.Relationships: Arbitrary, EntityRawIdType: Arbitrary {
 	public static var arbitrary: Gen<Entity<Description, MetaType, LinksType, EntityRawIdType>> {
 		return Gen.compose { c in
diff --git a/Sources/JSONAPIArbitrary/Relationship+Arbitrary.swift b/Sources/JSONAPIArbitrary/Relationship+Arbitrary.swift
index df1dd75..a1a8255 100644
--- a/Sources/JSONAPIArbitrary/Relationship+Arbitrary.swift
+++ b/Sources/JSONAPIArbitrary/Relationship+Arbitrary.swift
@@ -19,6 +19,10 @@ extension ToOneRelationship: Arbitrary where Identifiable.Identifier: Arbitrary,
 }
 
 extension ToOneRelationship where MetaType: Arbitrary, LinksType: Arbitrary {
+	/// Create a generator of arbitrary ToOneRelationships that will all
+	/// point to one of the given entities. This allows you to create
+	/// arbitrary relationships that make sense in a broader context where
+	/// the relationship must actually point to another entity.
 	public static func arbitrary<E: EntityType>(givenEntities: [E]) -> Gen<ToOneRelationship<Identifiable, MetaType, LinksType>> where E.Id == Identifiable.Identifier {
 
 		return Gen.compose { c in
@@ -41,6 +45,10 @@ extension ToManyRelationship: Arbitrary where Relatable.Identifier: Arbitrary, M
 }
 
 extension ToManyRelationship where MetaType: Arbitrary, LinksType: Arbitrary {
+	/// Create a generator of arbitrary ToManyRelationships that will all
+	/// point to some number of the given entities. This allows you to create
+	/// arbitrary relationships that make sense in a broader context where
+	/// the relationship must actually point to other existing entities.
 	public static func arbitrary<E: EntityType>(givenEntities: [E]) -> Gen<ToManyRelationship<Relatable, MetaType, LinksType>> where E.Id == Relatable.Identifier {
 		return Gen.compose { c in
 			let idsGen = Gen.fromElements(of: givenEntities).map { $0.id }.proliferate