tweak docstrings

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
 }

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))

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