From 5316561817469a23a51eff8c62db458259e72867 Mon Sep 17 00:00:00 2001
From: Martin Lange <martin.lange@ufz.de>
Date: Tue, 16 Jan 2024 15:15:08 +0100
Subject: [PATCH] tweak docstrings

---
 ecs/event.go         | 9 +++++----
 ecs/util.go          | 1 +
 listener/dispatch.go | 3 ++-
 3 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/ecs/event.go b/ecs/event.go
index a5273d93..37fd989c 100644
--- a/ecs/event.go
+++ b/ecs/event.go
@@ -25,11 +25,11 @@ import "github.com/mlange-42/arche/ecs/event"
 // This allows the [World] to be in an unlocked state, and notifies after potential entity initialization.
 type EntityEvent struct {
 	Entity                   Entity             // The entity that was changed.
-	Changed                  Mask               // Mask indicating changed components.
+	Changed                  Mask               // Mask indicating changed components (additions and removals).
 	Added, Removed           []ID               // Components added and removed. DO NOT MODIFY! Get the current components with [World.Ids].
 	OldRelation, NewRelation *ID                // Old and new relation component ID. No relation is indicated by nil.
 	OldTarget                Entity             // Old relation target entity. Get the new target with [World.Relations] and [Relations.Get].
-	EventTypes               event.Subscription // Bit mask of event types. See [Subscription].
+	EventTypes               event.Subscription // Bit mask of event types. See [event.Subscription].
 }
 
 // Contains returns whether the event's types contain the given type/subscription bit.
@@ -62,17 +62,18 @@ func newTestListener(callback func(e EntityEvent)) testListener {
 	}
 }
 
-// Notify the listener
+// Notify the listener.
 func (l *testListener) Notify(e EntityEvent) {
 	l.Callback(e)
 }
 
-// Subscriptions of the listener
+// Subscriptions of the listener in terms of event types.
 func (l *testListener) Subscriptions() event.Subscription {
 	return l.Subscribe
 }
 
 // Components the listener subscribes to.
+// Will be notified about changes on any (not all!) of the components in the mask.
 func (l *testListener) Components() *Mask {
 	return nil
 }
diff --git a/ecs/util.go b/ecs/util.go
index a2aa85d8..2f74d519 100644
--- a/ecs/util.go
+++ b/ecs/util.go
@@ -65,6 +65,7 @@ func subscription(entityCreated, entityRemoved, componentAdded, componentRemoved
 	return bits
 }
 
+// Returns whether a listener that subscribes to an event is also interested in terms of component subscription.
 func subscribes(evtType event.Subscription, changed *Mask, subs *Mask, oldRel *ID, newRel *ID) bool {
 	if event.Relations.Contains(evtType) {
 		return subs == nil || (oldRel != nil && subs.Get(*oldRel)) || (newRel != nil && subs.Get(*newRel))
diff --git a/listener/dispatch.go b/listener/dispatch.go
index 2fe8a8c8..518c65cd 100644
--- a/listener/dispatch.go
+++ b/listener/dispatch.go
@@ -8,8 +8,9 @@ import (
 // Dispatch event listener.
 //
 // Dispatches events to sub-listeners and manages subscription automatically.
-//
 // Sub-listeners should not alter their subscriptions or components after adding them.
+//
+// To make it possible for systems to add listeners, Dispatch should be added to the [ecs.World] as a resource.
 type Dispatch struct {
 	listeners     []ecs.Listener
 	events        event.Subscription