docs(event): update package docs

Author: bounoable

backend/mongo/store.go

@@ -17,8 +17,7 @@ import (
 	"github.com/modernice/goes/event/query/time"
 	"github.com/modernice/goes/event/query/version"
 	"github.com/modernice/goes/helper/pick"
-	"github.com/modernice/goes/internal/slice"
-		"go.mongodb.org/mongo-driver/bson"
+	"go.mongodb.org/mongo-driver/bson"
 	"go.mongodb.org/mongo-driver/mongo"
 	"go.mongodb.org/mongo-driver/mongo/options"
 	"go.mongodb.org/mongo-driver/x/mongo/driver"

event/doc.go

@@ -0,0 +1,49 @@
+// Package event is the core of goes. It defines and implements a generic event
+// system that is used as the building block for all the other components
+// provided by goes.
+//
+// The core type of this package is the Event interface. An event is either an
+// application event or an aggregate event, depending on the provided data.
+// Read the documentation of the Event interface for more information.
+//
+// To create an event, pass at least the name of the event and some arbitrary
+// event data to the New function:
+//
+//	evt := event.New("foo", 3)
+//	// evt.ID() == uuid.UUID{...}
+//	// evt.Name() == "foo"
+//	// evt.Time() == time.Now()
+//	// evt.Data() == 3
+//
+// Events can be published to subscribers over an event bus:
+//
+//	var bus event.Bus
+//	evt := event.New("foo", 3)
+//	err := bus.Publish(context.TODO(), evt)
+//
+// Events can also be subscribed to using an event bus:
+//
+//	// Subscribe to "foo", "bar", and "baz" events.
+//	events, errs, err := bus.Subscribe(context.TODO(), "foo", "bar", "baz")
+//
+// Events can be inserted into and queried from an event store:
+//
+//	var store event.Store
+//	evt := event.New("foo", 3)
+//	err := store.Insert(context.TODO(), evt)
+//
+//	events, errs, err := store.Query(context.TODO(), query.New(
+//		query.Name("foo"), // query "foo" events
+//		query.SortByTime(), // sort events by time
+//  ))
+//
+// Depending on the used event store and/or event bus implementations, it may be
+// required to pass an Encoding for your event data to the store/bus. Example
+// using encoding/gob for encoding of event data:
+//
+//	enc := codec.Gob(event.NewRegistry())
+//	codec.GobRegister[int](enc, "foo") // register "foo" as an int
+//	codec.GobRegister[string](enc, "bar") // register "bar" as a string
+//	codec.GobRegister[struct{Foo string}](enc, "baz") // register "baz" as a struct{Foo string}
+//	store := mongo.NewEventStore(enc)
+package event

event/event.go

@@ -1,7 +1,5 @@
 package event
 
-//go:generate mockgen -source=event.go -destination=./mocks/event.go
-
 import (
 	"sort"
 	stdtime "time"
@@ -12,31 +10,31 @@ import (
 	"github.com/modernice/goes/internal/xtime"
 )
 
-// Event is any event.
+// Event is an event with any data.
 type Event = Of[any]
 
-// An event describes something that has happened in the application or
-// specifically something that has happened to an aggregate in the application.
+// Of is an event with a specific data type. An event has a unique id, a name,
+// some arbitrary event data, and a time at which the event was raised. Behavior
+// for events that do not provide this data is not defined.
+//
+// If an event belongs to the stream of an aggregate, the Aggregate() method of
+// the event should return the aggregate's id and name, and the optimistic
+// concurrency version of the event.
+//
+// Events can be published over a Bus. When published, the event is sent to all
+// subscribers of the event that are subscribed to the event via the same Bus.
 //
-// Publish & Subscribe
+//	var bus event.Bus
+//	var evt event.Event
+//	err := bus.Publish(context.TODO(), evt)
 //
-// An event can be published through a Bus and sent to subscribers of Events
-// with the same name.
+// To subscribe to an event, call the Subscribe() method on a Bus:
 //
-// Example (publish):
-// 	var b event.Bus
-// 	evt := event.New("foo", someData{})
-// 	err := b.Publish(context.TODO(), evt)
-// 	// handle err
+//	var bus event.Bus
+//	// Subscribe to "foo", "bar", and "baz" events.
+//	events, errs, err := bus.Subscribe(context.TODO(), "foo", "bar", "baz")
 //
-// Example (subscribe):
-// 	var b event.Bus
-// 	res, errs, err := b.Subscribe(context.TODO(), "foo")
-// 	// handle err
-//	err := streams.Walk(context.TODO(), func(e event.Event) {
-// 	    log.Println(fmt.Sprintf("Received %q event: %v", e.Name(), e))
-//	}, res, errs)
-//	// handle err
+// Read the documentation of Bus for more details.
 type Of[Data any] interface {
 	// ID returns the unique id of the event.
 	ID() uuid.UUID