From b7c745950c207221c0523a5946f6a2440ddca296 Mon Sep 17 00:00:00 2001
From: Christian Treffs <ctreffs@gmail.com>
Date: Thu, 30 Jul 2020 16:03:59 +0200
Subject: [PATCH] Add documentation

---
 .../Nexus+ComponentsBuilder.swift             | 72 ++++++++++++++++---
 1 file changed, 64 insertions(+), 8 deletions(-)

diff --git a/Sources/FirebladeECS/Nexus+ComponentsBuilder.swift b/Sources/FirebladeECS/Nexus+ComponentsBuilder.swift
index 937f433..8e79b24 100644
--- a/Sources/FirebladeECS/Nexus+ComponentsBuilder.swift
+++ b/Sources/FirebladeECS/Nexus+ComponentsBuilder.swift
@@ -20,28 +20,84 @@ extension ComponentsBuilder {
     }
 
     public struct Context {
+        /// The index of the newly created entity.
+        ///
+        /// This is **NOT** equal to the entity identifier.
         public let index: Int
     }
 }
 
 extension Nexus {
+    /// Create an entity assigning one component.
+    ///
+    /// Usage:
+    /// ```
+    /// let newEntity = nexus.createEntity {
+    ///    Position(x: 1, y: 2)
+    /// }
+    /// ```
+    /// - Parameter builder: The component builder.
+    /// - Returns: The newly created entity with the provided component assigned.
     @discardableResult
-    public func createEntity(@ComponentsBuilder using componentBuilder: () -> Component) -> Entity {
-        self.createEntity(with: componentBuilder())
+    public func createEntity(@ComponentsBuilder using builder: () -> Component) -> Entity {
+        self.createEntity(with: builder())
     }
 
+    /// Create an entity assigning multiple components.
+    ///
+    /// Usage:
+    /// ```
+    /// let newEntity = nexus.createEntity {
+    ///    Position(x: 1, y: 2)
+    ///    Name(name: "Some name")
+    /// }
+    ///
+    /// // -- or --
+    ///
+    /// let compA = Position(x: 1, y: 2)
+    /// let compB = Name(name: "Some name")
+    ///
+    /// let newEntity = nexus.createEntity { compA; compB }
+    /// ```
+    /// - Parameter builder: The component builder.
+    /// - Returns: The newly created entity with the provided components assigned.
     @discardableResult
-    public func createEntity(@ComponentsBuilder using componentBuilder: () -> [Component]) -> Entity {
-        self.createEntity(with: componentBuilder())
+    public func createEntity(@ComponentsBuilder using builder: () -> [Component]) -> Entity {
+        self.createEntity(with: builder())
     }
 
+    /// Create multiple entities assigning one component each.
+    ///
+    /// Usage:
+    /// ```
+    /// let newEntities = nexus.createEntities(count: 100) { ctx in
+    ///    Velocity(a: Float(ctx.index))
+    /// }
+    /// ```
+    /// - Parameters:
+    ///   - count: The count of entities to create.
+    ///   - builder: The component builder providing context.
+    /// - Returns: The newly created entities with the provided component assigned.
     @discardableResult
-    public func createEntities(count: Int, @ComponentsBuilder using componentBuilder: (ComponentsBuilder.Context) -> Component) -> [Entity] {
-        (0..<count).map { self.createEntity(with: componentBuilder(ComponentsBuilder.Context(index: $0))) }
+    public func createEntities(count: Int, @ComponentsBuilder using builder: (ComponentsBuilder.Context) -> Component) -> [Entity] {
+        (0..<count).map { self.createEntity(with: builder(ComponentsBuilder.Context(index: $0))) }
     }
 
+    /// Create multiple entities assigning multiple components each.
+    ///
+    /// Usage:
+    /// ```
+    /// let newEntities = nexus.createEntities(count: 100) { ctx in
+    ///    Position(x: ctx.index, y: ctx.index)
+    ///    Name(name: "\(ctx.index)")
+    /// }
+    /// ```
+    /// - Parameters:
+    ///   - count: The count of entities to create.
+    ///   - builder: The component builder providing context.
+    /// - Returns: The newly created entities with the provided components assigned.
     @discardableResult
-    public func createEntities(count: Int, @ComponentsBuilder using componentBuilder: (ComponentsBuilder.Context) -> [Component]) -> [Entity] {
-        (0..<count).map { self.createEntity(with: componentBuilder(ComponentsBuilder.Context(index: $0))) }
+    public func createEntities(count: Int, @ComponentsBuilder using builder: (ComponentsBuilder.Context) -> [Component]) -> [Entity] {
+        (0..<count).map { self.createEntity(with: builder(ComponentsBuilder.Context(index: $0))) }
     }
 }