Documentation update and reformatting

Sources/PoieticCore/Constraints/Constraint+Node.swift

@@ -36,7 +36,7 @@ public final class UniqueNeighbourRequirement: ConstraintRequirement {
         self.isRequired = required
     }
 
-    public func check(frame: some Frame, objects: [any ObjectSnapshot]) -> [ObjectID] {
+    public func check(frame: some Frame, objects: [some ObjectSnapshot]) -> [ObjectID] {
         return objects.filter {
             guard $0.structure.type == .node else {
                 return false

Sources/PoieticCore/Constraints/Constraint.swift

@@ -5,12 +5,21 @@
 //  Created by Stefan Urbanek on 13/06/2022.
 //
 
+/// Error thrown when a constraint violation was found.
+///
+/// - SeeAlso: ``ConstraintChecker/check(_:)``, ``FrameConstraintError``
+///
 public struct ConstraintViolation: Error, CustomDebugStringConvertible {
+    /// Constraint that was violated.
     public let constraint: Constraint
+
+    /// List of objects that violated the constraint.
     public let objects: [ObjectID]
 
-    public init(constraint: Constraint,
-                objects: [ObjectID] = []) {
+    /// Create a constraint violation error for a given constraint and list of objects that violate
+    /// the constraints.
+    ///
+    public init(constraint: Constraint, objects: [ObjectID] = []) {
         self.constraint = constraint
         self.objects = objects
     }

Sources/PoieticCore/Design/Component.swift

@@ -67,8 +67,7 @@ public protocol InspectableComponent: Component, MutableKeyedAttributes {
     ///   likely included in the future.
     ///
     /// - Throws: ``ValueError`` if the value provided is of a type that can not
-    ///   be converted meaningfully to the attribute. ``AttributeError`` when
-    ///   trying to set an attribute that the component does not recognise.
+    ///   be converted meaningfully to the attribute.
     ///
     /// - SeeAlso: ``attribute(forKey:)``
     ///

Sources/PoieticCore/Design/TransientObject.swift

@@ -104,7 +104,7 @@ public class MutableObject: ObjectSnapshot {
 
     /// Set an attribute value for given key.
     ///
-    /// - Precondition: The attribute must not be a reserved attribute (``ObjectSnapshot/ReservedAttributeNames``).
+    /// - Precondition: The attribute must not be a reserved attribute (``ReservedAttributeNames``).
     ///
     public func setAttribute(value: Variant, forKey key: String) {
         precondition(ReservedAttributeNames.firstIndex(of: "key") == nil,

Sources/PoieticCore/Documentation.docc/MetamodelAndTypes.md

@@ -99,7 +99,6 @@ examples see ``Constraint``.
 - ``Constraint``
 - ``ConstraintChecker``
 - ``ObjectConstraintError``
-- ``EdgeEndpointTypes``
 - ``RejectAll``
 - ``AcceptAll``
 - ``ConstraintViolation``

Sources/PoieticCore/Expression/BuiltinFunctions.swift

@@ -17,24 +17,12 @@
 /// - `__le__` is `<=`
 ///
 nonisolated(unsafe)  public let BuiltinComparisonOperators: [Function] = [
-    .Comparison("__eq__") { (lhs, rhs) in
-        return lhs == rhs
-    },
-    .Comparison("__neq__") { (lhs, rhs) in
-        return lhs != rhs
-    },
-    .Comparison("__lt__") { (lhs, rhs) in
-        return try lhs < rhs
-    },
-    .Comparison("__le__") { (lhs, rhs) in
-        return try lhs <= rhs
-    },
-    .Comparison("__gt__") { (lhs, rhs) in
-        return try lhs > rhs
-    },
-    .Comparison("__ge__") { (lhs, rhs) in
-        return try lhs >= rhs
-    },
+    .Comparison("__eq__") { (lhs, rhs) in lhs == rhs },
+    .Comparison("__neq__") { (lhs, rhs) in lhs != rhs },
+    .Comparison("__lt__") { (lhs, rhs) in try lhs < rhs },
+    .Comparison("__le__") { (lhs, rhs) in try lhs <= rhs },
+    .Comparison("__gt__") { (lhs, rhs) in try lhs > rhs },
+    .Comparison("__ge__") { (lhs, rhs) in try lhs >= rhs },
 ]
 
 

Sources/PoieticCore/Foreign/FrameLoader.swift

@@ -89,7 +89,7 @@ public final class ForeignFrameLoader {
     ///         represent a transaction. When the function fails, the whole
     ///         frame should be discarded.
     /// - Throws: ``FrameLoaderError``
-    /// - SeeAlso: ``Design/allocateUnstructuredSnapshot(_:id:snapshotID:)``,
+    /// - SeeAlso: ``Design/allocateID(required:)``,
     ///     ``TransientFrame/insert(_:)``
     ///
     public func load(_ foreignFrame: ForeignFrame, into frame: TransientFrame) throws (FrameLoaderError) {

Sources/PoieticCore/Graph/Graph+algorithms.swift

@@ -11,18 +11,18 @@ extension GraphProtocol {
     /// - Returns: Sorted node IDs when there were no issues, or nil if there was a cycle.
     ///
     public func topologicalSort() -> [Node.ID]? {
-        var sorted: [Node.ID] = []
         var edges = self.edges
         let targets = Set(edges.map {$0.target})
         var sources: [Node.ID] =
             self.nodes.map { $0.id }.filter { !targets.contains($0) }
-
+        var sorted: [Node.ID] = []
+
         while !sources.isEmpty {
             let node: Node.ID = sources.removeFirst()
-            sorted.append(node)
-
             let outgoing: [Edge] = edges.filter { $0.origin == node }
 
+            sorted.append(node)
+
             for edge in outgoing {
                 let m: Node.ID = edge.target
 
@@ -47,15 +47,13 @@ extension GraphProtocol {
     /// - Returns: List of cycles
     ///
     public func cycles() -> [Edge] {
-        let nodes: [Node.ID] = self.nodes.map { $0.id }
         var edges = self.edges
-
+        let nodes: [Node.ID] = self.nodes.map { $0.id }
         let targets = Set(edges.map {$0.target})
         var sources: [Node.ID] = nodes.filter { !targets.contains($0) }
 
         while !sources.isEmpty {
             let node: Node.ID = sources.removeFirst()
-
             let outgoing: [Edge] = edges.filter { $0.origin == node }
 
             for edge in outgoing {

Sources/PoieticCore/Graph/Graph.swift

@@ -34,10 +34,14 @@ public protocol GraphProtocol {
 
     /// Get a node by ID.
     ///
+    /// - Precondition: The graph must contain the node.
+    ///
     func node(_ index: Node.ID) -> Node
 
     /// Get an edge by ID.
     ///
+    /// - Precondition: The graph must contain the edge.
+    ///
     func edge(_ index: Edge.ID) -> Edge
 
     /// Check whether the graph contains a node object with given ID.
@@ -62,11 +66,6 @@ public protocol GraphProtocol {
     ///
     /// - Complexity: O(n). All edges are traversed in the default implementation.
     ///
-    /// - Note: If you want to get both outgoing and incoming edges of a node
-    ///   then use ``neighbours(_:)``. Using ``outgoing(_:)`` + ``incoming(_:)`` might
-    ///   result in duplicates for edges that are loops to and from the same
-    ///   node.
-    ///
     func outgoing(_ origin: Node.ID) -> [Edge]
 
     /// Get a list of edges incoming to a node.
@@ -79,11 +78,6 @@ public protocol GraphProtocol {
     ///
     /// - Complexity: O(n). All edges are traversed in the default implementation.
     ///
-    /// - Note: If you want to get both outgoing and incoming edges of a node
-    ///   then use ``neighbours(_:)``. Using ``outgoing(_:)`` + ``incoming(_:)`` might
-    ///   result in duplicates for edges that are loops to and from the same
-    ///   node.
-    ///
     func incoming(_ target: Node.ID) -> [Edge]
 
     /// Get a neighbourhood of a node where the edges match the neighbourhood
@@ -103,21 +97,13 @@ extension GraphProtocol {
         return edges.contains { $0.id == edge }
     }
 
-    /// Get a node by ID.
-    ///
-    /// If id is `nil` then returns nil.
-    ///
     public func node(_ oid: Node.ID) -> Node {
         guard let first: Node = nodes.first(where: { $0.id == oid }) else {
             fatalError("Missing node")
         }
         return first
     }
 
-    /// Get an edge by ID.
-    ///
-    /// If id is `nil` then returns nil.
-    ///
     public func edge(_ oid: Edge.ID) -> Edge {
         guard let first:Edge = edges.first(where: { $0.id == oid }) else {
             fatalError("Missing edge")

Sources/PoieticCore/Graph/Neighborhood.swift

@@ -29,7 +29,7 @@ public enum EdgeDirection: Sendable {
 /// Neighbourhood is a subgraph centred on a node with edges adjacent to
 /// that node.
 ///
-/// Neighbourhoods are created using ``Graph/hood(_:selector:)``.
+/// Neighbourhoods are created using ``Graph/hood(_:direction:where:)``.
 ///
 public class Neighborhood<G: GraphProtocol> {
     public typealias GraphType = G

Sources/PoieticCore/Model/PositionTrait.swift

@@ -26,7 +26,7 @@ extension Trait {
 }
 
 extension ObjectSnapshot {
-    /// Get position of the object.
+    /// Get position of an object.
     ///
     /// The position is retrieved from the `position` attribute, if it is
     /// present. If the object has no `position` attribute or the attribute
@@ -45,7 +45,7 @@ extension ObjectSnapshot {
 }
 
 extension MutableObject {
-    /// Get or set position of the object.
+    /// Get or set position of an object.
     ///
     /// The position is retrieved from the `position` attribute, if it is
     /// present. If the object has no `position` attribute or the attribute

Sources/PoieticCore/Model/Trait.swift

@@ -46,8 +46,8 @@ public final class Trait: Sendable {
     ///   model validation in place, then which `name` will be used is
     ///   undeterminable.
     ///
-    /// - SeeAlso: ``ObjectSnapshot/subscript(attributeKey:)``,
-    ///   ``MutableObject/subscript(key:)``
+    /// - SeeAlso: ``ObjectSnapshot/subscript(_:)``,
+    ///   ``MutableObject/subscript(_:)``
     ///
     public let attributes: [Attribute]
 

Sources/PoieticCore/Predicate/Predicate.swift

@@ -1,13 +1,13 @@
 //
 //  Predicate.swift
-//  
+//
 //
 //  Created by Stefan Urbanek on 13/06/2022.
 //
 
 /// An object predicate.
 ///
-/// Predicates check properties of an object using the ``match(frame:object:)`` method.
+/// Predicates check properties of an object using the ``match(_:in:)`` method.
 ///
 /// Predicates can be composed using logical operations ``and(_:)`` and ``or(_:)``. For example:
 ///