More documentation

- Improved package top level doc
- Improved metamodel documentation

Sources/PoieticCore/Documentation.docc/Documentation.md

@@ -4,27 +4,23 @@ Core library for creating applications for systems thinking and simulation.
 
 ## Overview
 
-The Poietic Core provides functionality to iteratively construct models that
-are typically represented as a graph, such as Stock and Flow models,
-causal maps or biochemical pathways.
+The Poietic Core is a library that provides functionality to iteratively
+construct models of systems representable as graphs. One example of such models
+is a Stock and Flow model, a causal map or a biochemical pathways map.
 
 Particular focus features of the library are:
 
-- Allow user to experiment with a model design without worry.
 - Treat user's input as holy.
+- Allow user to experiment with a model design without worry.
 - Assure sustainability, evolvability and repairability of the design data.
 
 The core class of the model is the ``Design`` which contains and manages
-all the design objects – ``ObjectSnapshot`` – and their changes. The ``Design``
-also manages history of changes in form of frames which might be gathered in
-frame collections. One of the frame collections is the design history that
-features undo and redo functionality.
-
-The library focuses on category of models that are representable as graphs.
-The types for graph representation are mainly ``Graph``, ``Node`` and ``Edge``.
-For querying features of a graph there is ``Neighborhood`` and
-``NeighborhoodSelector``.
+all the design objects – ``ObjectSnapshot`` – and their changes in form of
+design frames ``Frame``.
 
+Designs are typically a part of a problem domain, or follow a methodology. The
+concepts and rules of the problem domain or a methodology or both are described
+in a ``Metamodel`` associated with the design. More in [Metamodel and Types](doc:MetamodelAndTypes).
 
 ## Topics
 

Sources/PoieticCore/Documentation.docc/MetamodelAndTypes.md

@@ -1,14 +1,15 @@
 # Metamodel and Types
 
 Metamodel defines types of the design objects and constraints that the design
-must satisfy to be considered valid.
+must satisfy to be considered valid within a modelled problem domain.
 
 ## Overview
 
-Metamodel represents a problem domain. The metamodel defines which types of
-objects the domain considers and what are the constraints or structural rules.
-The design objects must conform to the defined types and satisfy the constraints
-for the design to be valid within the problem domain.
+Metamodel represents a problem domain, methodology or a combination of both.
+The metamodel defines which types of objects the domain considers and
+what are the constraints or structural rules. The design objects must conform
+to the defined types and satisfy the constraints for the design to be valid
+within the problem domain.
 
 Example: A domain for modelling systems dynamics using stock and flows might
 consider node types _Stock_, _Flow_ and and _Drains_, _Fills_ edge types.
@@ -97,6 +98,7 @@ examples see ``Constraint``.
 
 - ``Constraint``
 - ``ConstraintChecker``
+- ``ObjectConstraintError``
 - ``EdgeEndpointTypes``
 - ``RejectAll``
 - ``AcceptAll``

Sources/PoieticCore/Documentation.docc/UnderstandingDesign.md

@@ -26,15 +26,16 @@ Each design is assigned a ``Metamodel``, which defines types of objects
 
 ### Object
 
+- ``ObjectSnapshot``
 - ``ObjectID``
-- ``SnapshotID``
 - ``StructuralComponent``
 - ``StructuralType``
+- ``SnapshotID``
 - ``ChildrenSet``
-- ``ObjectConstraintError``
 
 ### Design and Version Frames
 
+- ``Frame``
 - ``StableFrame``
 - ``MutableFrame``
 - ``FrameID``

Sources/PoieticCore/Model/Metamodel.swift

@@ -36,6 +36,8 @@ public final class Metamodel: Sendable {
     ///
     public let constraints: [Constraint]
 
+    /// Create a new empty metamodel.
+    ///
     public init() {
         self.name = nil
         self.traits = []
@@ -109,10 +111,30 @@ public final class Metamodel: Sendable {
         self.constraints = constraints
     }
 
+    /// Get an object type by its name.
+    ///
+    /// Example:
+    ///
+    /// ```swift
+    /// let metamodel = Metamodel.StockFlow
+    ///
+    /// let stockType = metamodel["Stock"]
+    /// let flowType = metamodel["Flow"]
+    /// ```
     public subscript(name: String) -> ObjectType? {
         return types.first { $0.name == name}
     }
 
+    /// Get an object type by its name.
+    ///
+    /// Example:
+    ///
+    /// ```swift
+    /// let metamodel = Metamodel.StockFlow
+    ///
+    /// let stockType = metamodel.objectType(name: "Stock")
+    /// let flowType = metamodel.objectType(name: "Flow")
+    /// ```
     public func objectType(name: String) -> ObjectType? {
         return types.first { $0.name == name}
     }