WIP: documentation

Sources/Setup/Dynamic Models/Entity.swift

@@ -28,46 +28,99 @@ import Foundation
 import ObjectiveC
 
 
-// MARK: - DynamicEntity
-
-public protocol DynamicEntity {
-    
-    var type: DynamicObject.Type { get }
-    var entityName: EntityName { get }
-    var isAbstract: Bool { get }
-    var versionHashModifier: String? { get }
-}
-
-
 // MARK: Entity
 
-public struct Entity<O: DynamicObject>: DynamicEntity, Hashable {
+/**
+ The `Entity<O>` contains `NSEntityDescription` metadata for `CoreStoreObject` subclasses. Pass the `Entity` instances to `CoreStoreSchema` initializer.
+ ```
+ class Animal: CoreStoreObject {
+     let species = Value.Required<String>("species")
+     let nickname = Value.Optional<String>("nickname")
+     let master = Relationship.ToOne<Person>("master")
+ }
+ 
+ class Person: CoreStoreObject {
+     let name = Value.Required<String>("name")
+     let pet = Relationship.ToOne<Animal>("pet", inverse: { $0.master })
+ }
+ 
+ CoreStore.defaultStack = DataStack(
+     CoreStoreSchema(
+         modelVersion: "V1",
+         entities: [
+             Entity<Animal>("Animal"),
+             Entity<Person>("Person")
+         ]
+     )
+ )
+ ```
+ - SeeAlso: CoreStoreSchema
+ - SeeAlso: CoreStoreObject
+ */
+public final class Entity<O: DynamicObject>: DynamicEntity {
     
-    public init(_ entityName: String, isAbstract: Bool = false, versionHashModifier: String? = nil) {
+    /**
+     Initializes an `Entity`. Always provide a concrete generic type to `Entity`.
+     ```
+     Entity<Animal>("Animal")
+     ```
+     - parameter entityName: the `NSEntityDescription` name to use for the entity
+     - parameter isAbstract: set to `true` if the entity is meant to be an abstract class and can only be initialized with subclass types.
+     - parameter versionHashModifier: The version hash modifier for the entity. Used to mark or denote an entity as being a different "version" than another even if all of the values which affect persistence are equal. (Such a difference is important in cases where, for example, the structure of an entity is unchanged but the format or content of data has changed.)
+     */
+    public convenience init(_ entityName: String, isAbstract: Bool = false, versionHashModifier: String? = nil) {
         
         self.init(O.self, entityName, isAbstract: isAbstract, versionHashModifier: versionHashModifier)
     }
     
+    /**
+     Initializes an `Entity`.
+     ```
+     Entity(Animal.self, "Animal")
+     ```
+     - parameter type: the `DynamicObject` type associated with the entity
+     - parameter entityName: the `NSEntityDescription` name to use for the entity
+     - parameter isAbstract: set to `true` if the entity is meant to be an abstract class and can only be initialized with subclass types.
+     - parameter versionHashModifier: The version hash modifier for the entity. Used to mark or denote an entity as being a different "version" than another even if all of the values which affect persistence are equal. (Such a difference is important in cases where, for example, the structure of an entity is unchanged but the format or content of data has changed.)
+     */
     public init(_ type: O.Type, _ entityName: String, isAbstract: Bool = false, versionHashModifier: String? = nil) {
         
-        self.type = type
-        self.entityName = entityName
-        self.isAbstract = isAbstract
-        self.versionHashModifier = versionHashModifier
+        super.init(type: type, entityName: entityName, isAbstract: isAbstract, versionHashModifier: versionHashModifier)
     }
+}
+
+
+// MARK: - DynamicEntity
+
+/**
+ Use concrete instances of `Entity<O>` in API that accept `DynamicEntity` arguments.
+ */
+public /*abstract*/ class DynamicEntity: Hashable {
     
-    
-    // MARK: DynamicEntity
-    
+    /**
+     Do not use directly.
+     */
     public let type: DynamicObject.Type
+    
+    /**
+     Do not use directly.
+     */
     public let entityName: EntityName
+    
+    /**
+     Do not use directly.
+     */
     public let isAbstract: Bool
+    
+    /**
+     Do not use directly.
+     */
     public let versionHashModifier: String?
     
     
     // MARK: Equatable
     
-    public static func == (lhs: Entity, rhs: Entity) -> Bool {
+    public static func == (lhs: DynamicEntity, rhs: DynamicEntity) -> Bool {
         
         return lhs.type == rhs.type
             && lhs.entityName == rhs.entityName
@@ -84,4 +137,15 @@ public struct Entity<O: DynamicObject>: DynamicEntity, Hashable {
             ^ self.isAbstract.hashValue
             ^ (self.versionHashModifier ?? "").hashValue
     }
+    
+    
+    // MARK: Internal
+    
+    internal init(type: DynamicObject.Type, entityName: String, isAbstract: Bool = false, versionHashModifier: String?) {
+        
+        self.type = type
+        self.entityName = entityName
+        self.isAbstract = isAbstract
+        self.versionHashModifier = versionHashModifier
+    }
 }