Add some docs, inlinable's

We cannot mark things like `Key` `Sendable` in an
easy way, because they refer to model objects.
Maybe we could drop that feature?

Sources/ZeeQL/Access/AttributeKey.swift

@@ -3,23 +3,30 @@
 //  ZeeQL
 //
 //  Created by Helge Hess on 02/03/17.
-//  Copyright © 2017 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2017-2024 ZeeZide GmbH. All rights reserved.
 //
 
+/**
+ * A ``Key`` that has access to an ``Attribute`` (an potentially the associated
+ * ``Entity``).
+ *
+ * The ``Key/key`` is the ``Attribute/name``.
+ */
 public struct AttributeKey : Key, Equatable {
 
   public var key : String { return attribute.name }
 
   public let entity    : Entity?
   public let attribute : Attribute
 
+  @inlinable
   public init(_ attribute: Attribute, entity: Entity? = nil) {
     self.attribute = attribute
     self.entity    = entity
   }
 
+  @inlinable
   public static func ==(lhs: AttributeKey, rhs: AttributeKey) -> Bool {
     return lhs.key == rhs.key
   }
-
 }

Sources/ZeeQL/Control/ComparisonOperation.swift

@@ -3,7 +3,7 @@
 //  ZeeQLTests
 //
 //  Created by Helge Heß on 24.08.19.
-//  Copyright © 2019 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2019-2024 ZeeZide GmbH. All rights reserved.
 //
 
 // TODO: Update to modern Swift API standards (e.g. lowercase)
@@ -105,6 +105,7 @@ public enum ComparisonOperation : Equatable, SmartDescription {
     ms += stringRepresentation
   }
 
+  @inlinable
   public static func ==(lhs: ComparisonOperation, rhs: ComparisonOperation)
                      -> Bool
   {
@@ -131,6 +132,7 @@ public extension ComparisonOperation {
   // Note: Had this as KeyValueQualifier<T>, but this makes class-checks harder.
   //       Not sure what the best Swift approach would be to avoid the Any
 
+  @inlinable
   func compare(_ a: Any?, _ b: Any?) -> Bool {
     // Everytime you compare an Any, a 🐄 dies.
     switch self {
@@ -178,3 +180,7 @@ public extension ComparisonOperation {
     }
   }
 }
+
+#if swift(>=5.5)
+extension ComparisonOperation: Sendable {}
+#endif

Sources/ZeeQL/Control/Key.swift

@@ -3,9 +3,25 @@
 //  ZeeQL
 //
 //  Created by Helge Hess on 15/02/2017.
-//  Copyright © 2017-2019 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2017-2024 ZeeZide GmbH. All rights reserved.
 //
 
+/**
+ * The `Key` protocol represents "keys" within qualifiers, like the left
+ * and right side of a ``KeyComparisonQualifier``.
+ *
+ * ``Attribute`` names, or directly ``Attribute``'s, or a ``KeyPath``.
+ *
+ * It has two main things:
+ * - ``key``: The key in the model, usually the name of an attribute,
+ *            but a `.` separated keypath for ``KeyPath`` keys.
+ * - ``append``: A method to form KeyPath'es (like `person.home.street`).
+ *
+ * Implementors:
+ * - ``StringKey``    (just wraps the plain string)
+ * - ``AttributeKey`` (has direct reference to the ``Attribute``)
+ * - ``KeyPath``
+ */
 public protocol Key : Expression, ExpressionEvaluation, EquatableType,
                       CustomStringConvertible
 {
@@ -55,9 +71,11 @@ public extension Key {
 public struct StringKey : Key, Equatable {
 
   public let key : String
-
+
+  @inlinable
   public init(_ key: String) { self.key = key }
 
+  @inlinable
   public static func ==(lhs: StringKey, rhs: StringKey) -> Bool {
     return lhs.key == rhs.key
   }
@@ -66,11 +84,17 @@ public struct StringKey : Key, Equatable {
 public struct KeyPath : Key, Equatable {
 
   public var keys : [ Key ]
+
+  /// Combines the keys into a `.` separated KeyPath.
+  @inlinable
   public var key  : String { return keys.map { $0.key }.joined(separator: ".") }
 
+  @inlinable
   public init(_ keys: Key...) { self.keys = keys }
+  @inlinable
   public init(keys: Key...)   { self.keys = keys }
 
+  @inlinable
   public static func ==(lhs: KeyPath, rhs: KeyPath) -> Bool {
     // TODO: just compare the arrays
     guard lhs.keys.count == rhs.keys.count else { return false }
@@ -88,16 +112,18 @@ public extension Key {
 
 extension StringKey : ExpressibleByStringLiteral {
 
+  @inlinable
   public init(stringLiteral value: String) {
     self.key = value
   }
 
+  @inlinable
   public init(extendedGraphemeClusterLiteral value: StringLiteralType) {
     self.key = value
   }
 
+  @inlinable
   public init(unicodeScalarLiteral value: StringLiteralType) {
     self.key = value
   }
-
 }

Sources/ZeeQL/Control/KeyComparisonQualifier.swift

@@ -3,7 +3,7 @@
 //  ZeeQL
 //
 //  Created by Helge Hess on 28/02/17.
-//  Copyright © 2017-2019 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2017-2024 ZeeZide GmbH. All rights reserved.
 //
 
 public struct KeyComparisonQualifier : Qualifier, Equatable {
@@ -12,25 +12,33 @@ public struct KeyComparisonQualifier : Qualifier, Equatable {
   public let rightKeyExpr : Key
   public let operation    : ComparisonOperation
 
+  @inlinable
   public init(_ left: Key, _ op: ComparisonOperation = .EqualTo, _ right: Key) {
     self.leftKeyExpr  = left
     self.rightKeyExpr = right
     self.operation    = op
   }
+  @inlinable
   public init(_ left: String, _ op: String = "==", _ right: String) {
     self.init(StringKey(left),
               ComparisonOperation(string: op),
               StringKey(right))
   }
 
+  @inlinable
   public var leftKey  : String { return leftKeyExpr.key  }
+  @inlinable
   public var rightKey : String { return rightKeyExpr.key }
 
+  @inlinable
   public var leftExpression  : Expression { return leftKeyExpr  }
+  @inlinable
   public var rightExpression : Expression { return rightKeyExpr }
 
+  @inlinable
   public var isEmpty : Bool { return false }
 
+  @inlinable
   public func addReferencedKeys(to set: inout Set<String>) {
     set.insert(leftKeyExpr.key)
     set.insert(rightKeyExpr.key)
@@ -39,11 +47,13 @@ public struct KeyComparisonQualifier : Qualifier, Equatable {
 
   // MARK: - Bindings
 
+  @inlinable
   public var hasUnresolvedBindings : Bool { return false }
 
 
   // MARK: - Equality
 
+  @inlinable
   public static func ==(lhs: KeyComparisonQualifier,
                         rhs: KeyComparisonQualifier) -> Bool
   {
@@ -53,6 +63,7 @@ public struct KeyComparisonQualifier : Qualifier, Equatable {
     return true
   }
 
+  @inlinable
   public func isEqual(to object: Any?) -> Bool {
     guard let other = object as? KeyComparisonQualifier else { return false }
     return self == other