From feee72d2f673fb58e1d672d1aa8ef7da7d9e8007 Mon Sep 17 00:00:00 2001
From: Ullrich Praetz <ullrich@praetz.de>
Date: Wed, 31 Jul 2024 10:18:59 +0200
Subject: [PATCH] ECS - Add docs for EntityState and EntityStore.RecycleIds

---
 src/ECS/Archetype/Archetype.cs |  4 +++-
 src/ECS/Entity.cs              |  1 +
 src/ECS/Entity/EntityState.cs  | 14 ++++++++++++++
 src/ECS/EntityStore.cs         |  4 ++++
 4 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/src/ECS/Archetype/Archetype.cs b/src/ECS/Archetype/Archetype.cs
index eea428a2..687093bb 100644
--- a/src/ECS/Archetype/Archetype.cs
+++ b/src/ECS/Archetype/Archetype.cs
@@ -321,7 +321,9 @@ internal static int AddEntity(Archetype arch, int id)
     }
     
     private static void ResizeGrow  (Archetype arch) => Resize(arch, 2 * arch.memory.capacity);
-    private static void ResizeShrink(Archetype arch) => Resize(arch, 2 * arch.memory.shrinkThreshold);
+    private static void ResizeShrink(Archetype arch) {
+        // Resize(arch, 2 * arch.memory.shrinkThreshold);
+    }
     
     private static void Resize(Archetype arch, int capacity)
     {
diff --git a/src/ECS/Entity.cs b/src/ECS/Entity.cs
index 3a023469..5f0c1257 100644
--- a/src/ECS/Entity.cs
+++ b/src/ECS/Entity.cs
@@ -253,6 +253,7 @@ public     ref readonly Tags                Tags { get {
 
     // ------------------------------------ component properties ----------------------------------
 #region component - properties
+    /// <summary> Returns the entity state used to optimize read / write access to entity components. </summary>
     [Browse(Never)] public EntityState State { get {
         ref var node    = ref store.nodes[Id];
         var type        = archetype;
diff --git a/src/ECS/Entity/EntityState.cs b/src/ECS/Entity/EntityState.cs
index 92ae5541..140e93c6 100644
--- a/src/ECS/Entity/EntityState.cs
+++ b/src/ECS/Entity/EntityState.cs
@@ -2,15 +2,29 @@
 // See LICENSE file in the project root for full license information.
 
 // ReSharper disable once CheckNamespace
+
+using System;
+
 namespace Friflo.Engine.ECS;
 
+/// <summary>
+/// An <see cref="EntityState"/> is used to optimize read / write access of entity components.br/>
+/// An instance can be returned by <see cref="Entity.State"/>. 
+/// </summary>
 public readonly ref struct EntityState
 {
 #region entity getter
+    /// <summary> Returns true is the entity is deleted. </summary>
+    /// <remarks>Executes in O(1)</remarks>
     public  bool        IsNull          => archetype == null;
     
+    /// <summary> Return the <see cref="ECS.Tags"/> added to an entity. </summary>
+    /// <remarks>Executes in O(1)</remarks>
     public  Tags        Tags            => archetype.tags;
     
+    /// <summary>Return the component of the given type as a reference.</summary>
+    /// <exception cref="NullReferenceException"> if entity has no component of Type <typeparamref name="T"/></exception>
+    /// <remarks>Executes in O(1)</remarks>
     public  ref T       Get<T>() where T : struct, IComponent {
         return ref ((StructHeap<T>)archetype.heapMap[StructInfo<T>.Index]).components[compIndex];
     }
diff --git a/src/ECS/EntityStore.cs b/src/ECS/EntityStore.cs
index 8e1cfb21..901b599b 100644
--- a/src/ECS/EntityStore.cs
+++ b/src/ECS/EntityStore.cs
@@ -66,6 +66,10 @@ public sealed partial class EntityStore : EntityStoreBase
     /// <summary> Get the number of internally reserved entities. </summary>
     [Browse(Never)] public              int                 Capacity        => nodes.Length;
     
+    /// <summary>
+    /// If true ids of deleted entities are recycled when creating new entities.<br/>
+    /// If false every new entity gets its own unique id. As a result the store capacity will always grow over time.   
+    /// </summary>
     [Browse(Never)] public              bool                RecycleIds      { get => recycleIds; set => SetRecycleIds(value); }
     
     /// <summary> Return store information used for debugging and optimization. </summary>