Reorganization, documentation

Author: Revolucent

CoreDataQueryInterface/Attribute.swift

@@ -43,6 +43,9 @@ public class Attribute: CustomStringConvertible, CustomExpressionConvertible, Pr
         _parent = parent
         _type = type
     }
+    /**
+     Returns the attribute as a keypath.
+    */
     public private(set) lazy var description: String = {
         if let parent = self._parent {
             let parentName = String(parent)
@@ -52,6 +55,11 @@ public class Attribute: CustomStringConvertible, CustomExpressionConvertible, Pr
             return self._name ?? ""
         }
     }()
+    /**
+     The `NSExpression` to which this attribute resolves.
+     
+     - note: This is usually a keypath expression.
+    */
     public private(set) lazy var expression: NSExpression = {
         let keyPath = String(self)
         if keyPath.hasPrefix("$") {
@@ -62,6 +70,10 @@ public class Attribute: CustomStringConvertible, CustomExpressionConvertible, Pr
             return NSExpression(forKeyPath: keyPath)
         }
     }()
+    
+    /**
+     
+    */
     public func named(name: String, type: NSAttributeType? = nil) -> NSExpressionDescription {
         let e = NSExpressionDescription()
         e.expression = expression
@@ -99,9 +111,3 @@ extension Aggregable where Self: Attribute {
         return AggregateType("@min", parent: self)
     }
 }
-
-extension Attribute: CustomPropertyConvertible {
-    public var property: AnyObject {
-        return String(self)
-    }
-}

CoreDataQueryInterface/BooleanAttribute.swift

@@ -25,13 +25,6 @@ SOFTWARE.
 import CoreData
 import Foundation
 
-extension Bool: TypedExpressionConvertible {
-    public typealias ExpressionValueType = Bool
-    public var expression: NSExpression {
-        return NSExpression(forConstantValue: self)
-    }
-}
-
 public class BooleanAttribute: Attribute, TypedExpressionConvertible {
     public typealias ExpressionValueType = Bool
     public required init(_ name: String, parent: Attribute? = nil, type: NSAttributeType? = nil) {
@@ -42,3 +35,9 @@ public class BooleanAttribute: Attribute, TypedExpressionConvertible {
     }
 }
 
+extension Bool: TypedExpressionConvertible {
+    public typealias ExpressionValueType = Bool
+    public var expression: NSExpression {
+        return NSExpression(forConstantValue: self)
+    }
+}

CoreDataQueryInterface/CustomPropertyConvertible.swift

@@ -25,6 +25,13 @@ SOFTWARE.
 import Foundation
 import CoreData
 
+/**
+ Represents a type that can be used with `NSFetchRequest`'s `propertiesToFetch`
+ and `propertiesToGroupBy` properties.
+ 
+ - note: In Swift, these properties have the type `[AnyObject]` (i.e., `NSArray`), but
+ in practice only strings and subtypes of `NSPropertyDescription` can be used.
+ */
 public protocol CustomPropertyConvertible {
     var property: AnyObject { get }
 }
@@ -41,3 +48,8 @@ extension NSPropertyDescription: CustomPropertyConvertible {
     }
 }
 
+extension Attribute: CustomPropertyConvertible {
+    public var property: AnyObject {
+        return String(self)
+    }
+}

CoreDataQueryInterface/DataAttribute.swift

@@ -25,13 +25,6 @@ SOFTWARE.
 import CoreData
 import Foundation
 
-extension NSData: TypedExpressionConvertible {
-    public typealias ExpressionValueType = NSData
-    public var expression: NSExpression {
-        return NSExpression(forConstantValue: self)
-    }
-}
-
 public class DataAttribute: Attribute, TypedExpressionConvertible {
     public typealias ExpressionValueType = NSData
     public required init(_ name: String, parent: Attribute? = nil, type: NSAttributeType? = nil) {
@@ -42,3 +35,10 @@ public class DataAttribute: Attribute, TypedExpressionConvertible {
     }
 }
 
+extension NSData: TypedExpressionConvertible {
+    public typealias ExpressionValueType = NSData
+    public var expression: NSExpression {
+        return NSExpression(forConstantValue: self)
+    }
+}
+

CoreDataQueryInterface/EntityAttribute.swift

@@ -25,13 +25,6 @@ SOFTWARE.
 import Foundation
 import CoreData
 
-extension NSManagedObject: TypedExpressionConvertible, ComparableExpression {
-    public typealias ExpressionValueType = NSManagedObject
-    public var expression: NSExpression {
-        return NSExpression(forConstantValue: self)
-    }
-}
-
 public class EntityAttribute: Attribute, TypedExpressionConvertible {
     public typealias ExpressionValueType = NSManagedObject
     public required init(_ name: String, parent: Attribute? = nil, type: NSAttributeType? = nil) {
@@ -41,3 +34,11 @@ public class EntityAttribute: Attribute, TypedExpressionConvertible {
         super.init()
     }
 }
+
+extension NSManagedObject: TypedExpressionConvertible, ComparableExpression {
+    public typealias ExpressionValueType = NSManagedObject
+    public var expression: NSExpression {
+        return NSExpression(forConstantValue: self)
+    }
+}
+

CoreDataQueryInterface/Selecting.swift

@@ -27,38 +27,68 @@ import Foundation
 
 extension ExpressionQueryType {
 
+    /**
+     Projection, i.e., select attributes of an entity rather than the entities themselves.
+     
+     `CustomPropertyConvertible` is implemented by `String`, `Attribute` and `NSPropertyDescription`,
+     so any of these can be used here.
+    */
     public func select(expressions: [CustomPropertyConvertible]) -> ExpressionQuery<QueryEntityType> {
         var builder = self.builder
         builder.expressions.appendContentsOf(expressions)
         return ExpressionQuery(builder: builder)
     }
-    
+
+    /**
+     Projection, i.e., select attributes of an entity rather than the entities themselves.
+     
+     `CustomPropertyConvertible` is implemented by `String`, `Attribute` and `NSPropertyDescription`,
+     so any of these can be used here.
+    */
     public func select(expressions: CustomPropertyConvertible...) -> ExpressionQuery<QueryEntityType> {
         return select(expressions)
     }
 
+    /**
+     Projection, i.e., select attributes of an entity rather than the entities themselves.
+     
+         .select(employee in [employee.firstName, employee.lastName])
+    */
     public func select(expressions: QueryEntityType.EntityAttributeType -> [CustomPropertyConvertible]) -> ExpressionQuery<QueryEntityType> {
         let attribute = QueryEntityType.EntityAttributeType()
         return select(expressions(attribute))
     }
-    
+
+    /**
+     Projection, i.e., select attributes of an entity rather than the entities themselves.
+
+         .select([{$0.firstName}, {$0.lastName}])
+    */
     public func select(expressions: [QueryEntityType.EntityAttributeType -> CustomPropertyConvertible]) -> ExpressionQuery<QueryEntityType> {
         let attribute = QueryEntityType.EntityAttributeType()
         return select(expressions.map() { $0(attribute) })
     }
-    
+
+    /**
+     Projection, i.e., select attributes of an entity rather than the entities themselves.
+     
+         .select({$0.firstName}, {$0.lastName})
+    */
     public func select(expressions: (QueryEntityType.EntityAttributeType -> CustomPropertyConvertible)...) -> ExpressionQuery<QueryEntityType> {
         return select(expressions)
     }
 
+    /**
+     Return only the distinct attributes requested in the fetch.
+    */
     public func distinct() -> ExpressionQuery<QueryEntityType> {
         var builder = self.builder
         builder.returnsDistinctResults = true
         return ExpressionQuery(builder: builder)
     }
 
     /**
-    Resets the list of selected expressions
+     Resets the list of selected expressions
     */
     public func reselect() -> ExpressionQuery<QueryEntityType> {
         var builder = self.builder