From 0668be06e2cb48d2583712e70a47cd69f8e304dd Mon Sep 17 00:00:00 2001
From: SeanOMik <seanomik@gmail.com>
Date: Wed, 10 Apr 2024 23:18:11 -0400
Subject: [PATCH] ecs: documentation improvements for filter queries

---
 .../query/filter/{has_component.rs => has.rs} |  4 ++
 lyra-ecs/src/query/filter/mod.rs              |  8 ++--
 lyra-ecs/src/query/filter/not.rs              | 37 +++++++++----------
 lyra-ecs/src/query/filter/or.rs               | 21 +++++++++++
 4 files changed, 47 insertions(+), 23 deletions(-)
 rename lyra-ecs/src/query/filter/{has_component.rs => has.rs} (77%)

diff --git a/lyra-ecs/src/query/filter/has_component.rs b/lyra-ecs/src/query/filter/has.rs
similarity index 77%
rename from lyra-ecs/src/query/filter/has_component.rs
rename to lyra-ecs/src/query/filter/has.rs
index 1ef455a..cc5cf99 100644
--- a/lyra-ecs/src/query/filter/has_component.rs
+++ b/lyra-ecs/src/query/filter/has.rs
@@ -2,6 +2,10 @@ use std::marker::PhantomData;
 
 use crate::{query::{AsQuery, Query}, Archetype, Component, DynTypeId, World};
 
+/// A filter query that fetches when the entity has the component `C`.
+/// 
+/// This does not return a reference to the component, it returns `()` if the entity has
+/// the component. This query is great when its used with [`Or`](super::Or).
 #[derive(Default)]
 pub struct Has<C: Component> {
     _marker: PhantomData<C>
diff --git a/lyra-ecs/src/query/filter/mod.rs b/lyra-ecs/src/query/filter/mod.rs
index 8fe360c..e9bb05b 100644
--- a/lyra-ecs/src/query/filter/mod.rs
+++ b/lyra-ecs/src/query/filter/mod.rs
@@ -1,8 +1,8 @@
-pub mod has_component;
-pub use has_component::*;
+mod has;
+pub use has::*;
 
-pub mod or;
+mod or;
 pub use or::*;
 
-pub mod not;
+mod not;
 pub use not::*;
\ No newline at end of file
diff --git a/lyra-ecs/src/query/filter/not.rs b/lyra-ecs/src/query/filter/not.rs
index f020415..4257261 100644
--- a/lyra-ecs/src/query/filter/not.rs
+++ b/lyra-ecs/src/query/filter/not.rs
@@ -1,22 +1,22 @@
-use std::marker::PhantomData;
-
 use crate::{query::{AsQuery, Query}, Archetype, World};
 
-#[derive(Default)]
+/// A filter query that fetches the inverse of `Q`.
+/// 
+/// This means that entities that `Q` fetches are skipped, and entities that
+/// `Q` does not fetch are not skipped.
+/// 
+/// ```rust,nobuild
+/// // Iterate over entities that has a transform, and are not the origin of a `ChildOf` relationship.
+/// for (en, pos, _) in world
+///     .view::<(Entities, &Transform, Not<Has<RelationOriginComponent<ChildOf>>>)>()
+///     .iter()
+/// {
+///     // ...
+/// }
+/// ```
+#[derive(Default, Copy, Clone)]
 pub struct Not<Q: Query> {
-    q: Q,
-    _marker: PhantomData<Q>
-}
-
-impl<Q: Query> Copy for Not<Q> {}
-
-impl<Q: Query> Clone for Not<Q> {
-    fn clone(&self) -> Self {
-        Self { 
-            q: self.q.clone(),
-            _marker: self._marker.clone()
-        }
-    }
+    query: Q,
 }
 
 impl<Q: Query> Query for Not<Q> {
@@ -26,13 +26,12 @@ impl<Q: Query> Query for Not<Q> {
 
     fn new() -> Self {
         Not {
-            q: Q::new(),
-            _marker: PhantomData
+            query: Q::new(),
         }
     }
 
     fn can_visit_archetype(&self, archetype: &Archetype) -> bool {
-        !self.q.can_visit_archetype(archetype)
+        !self.query.can_visit_archetype(archetype)
     }
 
     unsafe fn fetch<'a>(&self, _world: &'a World, _: &'a Archetype, _: crate::Tick) -> Self::Fetch<'a> {
diff --git a/lyra-ecs/src/query/filter/or.rs b/lyra-ecs/src/query/filter/or.rs
index c76d9d8..45a376f 100644
--- a/lyra-ecs/src/query/filter/or.rs
+++ b/lyra-ecs/src/query/filter/or.rs
@@ -1,5 +1,26 @@
 use crate::{query::{AsQuery, Query}, Archetype, World};
 
+/// A filter query returning when either `Q1` or `Q2` returns.
+/// 
+/// This checks if `Q1` can fetch before checking `Q2`.
+/// 
+/// ```rust,nobuild
+/// for (en, pos, _) in world
+///     .view::<(Entities, &Transform, Or<Has<Mesh>, Has<Scene>>)>()
+///     .iter()
+/// {
+///     // do some things with the position of the entities
+/// 
+///     // now handle do things with the Mesh or Scene that the entity could have
+///     if let Some(mesh) = world.view_one::<&Mesh>(en).get() {
+///         // do mesh things
+///     }
+/// 
+///     if let Some(scene) = world.view_one::<&Scene>(en).get() {
+///         // do scene things
+///     }
+/// }
+/// ```
 #[derive(Default)]
 pub struct Or<Q1: AsQuery, Q2: AsQuery> {
     left: Q1::Query,