From b1810a25fe9b895cf9b64752c09c8b43c012a281 Mon Sep 17 00:00:00 2001
From: silly-spongus <159207316+silly-spongus@users.noreply.github.com>
Date: Fri, 20 Sep 2024 20:28:29 -0300
Subject: [PATCH 1/3] Improvements to "Query" API Docs

Minor improvements, but mostly made this fit more with the PR i made for World
---
 docs/api/query.md | 58 +++++++++++++++++++++++++++++------------------
 1 file changed, 36 insertions(+), 22 deletions(-)

diff --git a/docs/api/query.md b/docs/api/query.md
index 57390c8..51abee5 100644
--- a/docs/api/query.md
+++ b/docs/api/query.md
@@ -2,27 +2,30 @@
 
 A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components.
 
-# Functions
+To create a query, you must utilize [`world:query`](world).
 
-## drain()
+## Methods
+
+### drain
+This method will impede it from being reset when the query is being iterated.
 ```luau
 function query:drain(): Query
 ```
-This function will impede it from being reset when the query is being iterated.
 
-## next()
+### next
+Get the next result in the query. Drain must have been called beforehand or otherwise it will error.
 ```luau
 function query:next(): Query
 ```
-Get the next result in the query. Drain must have been called beforehand or otherwise it will error.
 
-## with()
+### with
+Adds components (IDs) to query with, but will not use their data. This is useful for Tags or generally just data you do not care for.
+
 ```luau
 function query:with(
     ...: Entity -- The IDs to query with
 ): Query
 ```
-Adds IDs to query with, but will not use their data. This is useful for Tags or generally just data you do not care for.
 
 Example:
 ::: code-group
@@ -45,43 +48,41 @@ for (const [id, position] of world.query(Position).with(Velocity)) {
 Put the IDs inside of `world:query()` instead if you need the data.
 :::
 
-## without()
+### without
+Removes entities with the provided components from the query.
 
 ```luau
 function query:without(
     ...: Entity -- The IDs to filter against.
 ): Query -- Returns the Query
 ```
-Removes entities with the provided IDs from the query.
 
 Example:
-::: code-group
 
+::: code-group
 ```luau [luau]
-for _ in world:query(Position):without(Velocity) do
+for entity, position in world:query(Position):without(Velocity) do
     -- Do something
 end
 ```
 
 ```ts [typescript]
-for (const _ of world.query(Position).without(Velocity)) {
+for (const [entity, position] of world.query(Position).without(Velocity)) {
     // Do something
 }
 ```
-
 :::
 
-## replace()
-
+### replace
+This function takes a callback which is given the current queried data of each matching entity. The values returned by the callback will be set as the new data for each given ID on the entity.
 ```luau
 function query:replace(
     fn: (entity: Entity, ...: T...) -> U... -- ): () -- The callback that will transform the entities' data
 ```
-This function takes a callback which is given the current queried data of each matching entity. The values returned by the callback will be set as the new data for each given ID on the entity.
 
 Example:
-::: code-group
 
+::: code-group
 ```luau [luau]
 world:query(Position, Velocity):replace(function(e, position, velocity)
     return position + velocity, velocity * 0.9
@@ -95,19 +96,17 @@ world
         $tuple(position.add(velocity), velocity.mul(0.9)),
     );
 ```
-
 :::
 
-
-## archetypes()
+### archetypes
+Returns the matching archetypes of the query.
 ```luau
 function query.archetypes(): { Archetype }
 ```
-Returns the matching archetypes of the query.
 
 Example:
-::: code-group
 
+::: code-group
 ```luau [luau]
 for i, archetype in world:query(Position, Velocity).archetypes() do
     local columns = archetype.columns
@@ -124,6 +123,21 @@ for i, archetype in world:query(Position, Velocity).archetypes() do
 end
 ```
 
+```ts [typescript]
+for (const [i, archetype] of world.query(Position, Velocity).archetypes()) {
+    const columns = archetype.columns;
+    const field = archetype.records;
+
+    const P = field[Position];
+    const V = field[Velocity];
+
+    for (const [row, entity] of archetype.entities) {
+        local position = columns[P][row];
+        local velocity = columns[V][row];
+        // Do something
+    }
+}
+```
 :::
 
 :::info

From 561a3a77de527a25b71c1029ab6e96c81286e046 Mon Sep 17 00:00:00 2001
From: silly-spongus <159207316+silly-spongus@users.noreply.github.com>
Date: Sun, 29 Sep 2024 04:13:21 -0300
Subject: [PATCH 2/3] Update query.md

---
 docs/api/query.md | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/docs/api/query.md b/docs/api/query.md
index 51abee5..3b4a40e 100644
--- a/docs/api/query.md
+++ b/docs/api/query.md
@@ -2,23 +2,21 @@
 
 A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components.
 
-To create a query, you must utilize [`world:query`](world).
+# Methods
 
-## Methods
-
-### drain
+## drain
 This method will impede it from being reset when the query is being iterated.
 ```luau
 function query:drain(): Query
 ```
 
-### next
+## next
 Get the next result in the query. Drain must have been called beforehand or otherwise it will error.
 ```luau
 function query:next(): Query
 ```
 
-### with
+## with
 Adds components (IDs) to query with, but will not use their data. This is useful for Tags or generally just data you do not care for.
 
 ```luau
@@ -48,7 +46,7 @@ for (const [id, position] of world.query(Position).with(Velocity)) {
 Put the IDs inside of `world:query()` instead if you need the data.
 :::
 
-### without
+## without
 Removes entities with the provided components from the query.
 
 ```luau
@@ -73,7 +71,7 @@ for (const [entity, position] of world.query(Position).without(Velocity)) {
 ```
 :::
 
-### replace
+## replace
 This function takes a callback which is given the current queried data of each matching entity. The values returned by the callback will be set as the new data for each given ID on the entity.
 ```luau
 function query:replace(
@@ -98,7 +96,7 @@ world
 ```
 :::
 
-### archetypes
+## archetypes
 Returns the matching archetypes of the query.
 ```luau
 function query.archetypes(): { Archetype }

From 27235382c99bd10c6d145c059329f05c4c585ea1 Mon Sep 17 00:00:00 2001
From: silly-spongus <159207316+silly-spongus@users.noreply.github.com>
Date: Sun, 29 Sep 2024 04:14:39 -0300
Subject: [PATCH 3/3] Update query.md

---
 docs/api/query.md | 18 ------------------
 1 file changed, 18 deletions(-)

diff --git a/docs/api/query.md b/docs/api/query.md
index 3b4a40e..24aab6f 100644
--- a/docs/api/query.md
+++ b/docs/api/query.md
@@ -104,7 +104,6 @@ function query.archetypes(): { Archetype }
 
 Example:
 
-::: code-group
 ```luau [luau]
 for i, archetype in world:query(Position, Velocity).archetypes() do
     local columns = archetype.columns
@@ -121,23 +120,6 @@ for i, archetype in world:query(Position, Velocity).archetypes() do
 end
 ```
 
-```ts [typescript]
-for (const [i, archetype] of world.query(Position, Velocity).archetypes()) {
-    const columns = archetype.columns;
-    const field = archetype.records;
-
-    const P = field[Position];
-    const V = field[Velocity];
-
-    for (const [row, entity] of archetype.entities) {
-        local position = columns[P][row];
-        local velocity = columns[V][row];
-        // Do something
-    }
-}
-```
-:::
-
 :::info
 This function is meant for internal usage. Use this if you want to maximize performance by inlining the iterator.
 :::