docs: add comments to explain functions and methods in various test f…

…iles

This commit adds comments to explain the purpose and functionality of
functions and methods in various test files, improving code readability
and providing better context for developers.

docs: add comments to various structs and methods in test files

Add comments to explain the purpose and functionality of various structs
and methods in test files, improving code readability and understanding
for future developers.

test(job_test.go): add comments to newDelayedEventStore.Query method for better understanding
docs(lookup.go): add comments to lookup interface and Lookup method for better documentation
test(lookup_test.go): add comments to LookupEvent struct and ProvideLookup method for better understanding

aggregate/query/query.go

@@ -102,6 +102,8 @@ type Tagger interface {
 type queryWithTags interface {
 	aggregate.Query
 
+	// Tags returns the tags for a queryWithTags. It filters aggregates that
+	// implement Tagger based on their tags.
 	Tags() []string
 }
 
@@ -167,12 +169,12 @@ func Test[D any](q aggregate.Query, a aggregate.Aggregate) bool {
 // In order for the returned Query to return the correct events, EventQueryOpts
 // needs to rewrite some of the version filters to make sense for an aggregate-
 // specific event.Query:
-// 	- version.Exact is rewritten to version.Max
-// 		(querying for version 10 of an aggregate should return events 1 -> 10)
-// 	- version.Max is passed without modification
-// 	- version.Min is discarded
-// 		(because an aggregate cannot start at a version > 1)
-// 	- version.Ranges is rewritten to version.Max
+//   - version.Exact is rewritten to version.Max
+//     (querying for version 10 of an aggregate should return events 1 -> 10)
+//   - version.Max is passed without modification
+//   - version.Min is discarded
+//     (because an aggregate cannot start at a version > 1)
+//   - version.Ranges is rewritten to version.Max
 func EventQueryOpts(q aggregate.Query) []query.Option {
 	var opts []query.Option
 	if names := q.Names(); len(names) > 0 {

aggregate/repository/mongo_test.go

@@ -65,6 +65,10 @@ func newRetryer() *retryer {
 	}
 }
 
+// RetryUse returns a RetryTrigger and an IsRetryable function for the retryer.
+// The RetryTrigger specifies to retry every 50 milliseconds for a maximum of 4
+// times, and the IsRetryable function checks if an error is a consistency
+// error.
 func (r *retryer) RetryUse() (repository.RetryTrigger, repository.IsRetryable) {
 	return repository.RetryEvery(50*time.Millisecond, 4), aggregate.IsConsistencyError
 }

aggregate/repository/repository_test.go

@@ -806,12 +806,16 @@ type mockState struct {
 	A string
 }
 
+// MarshalSnapshot encodes the mockState of a mockAggregate into a byte slice.
+// It returns the encoded byte slice and any error encountered during encoding.
 func (a *mockAggregate) MarshalSnapshot() ([]byte, error) {
 	var buf bytes.Buffer
 	err := gob.NewEncoder(&buf).Encode(a.mockState)
 	return buf.Bytes(), err
 }
 
+// UnmarshalSnapshot decodes the provided snapshot data and updates the
+// aggregate state with the decoded mockState.
 func (a *mockAggregate) UnmarshalSnapshot(p []byte) error {
 	return gob.NewDecoder(bytes.NewReader(p)).Decode(&a.mockState)
 }

aggregate/repository/soft_delete_test.go

@@ -107,8 +107,12 @@ func TestRepository_Query_SoftDelete(t *testing.T) {
 
 type softDeletedEvent struct{}
 
+// SoftDelete returns true, indicating that the softDeletedEvent represents a
+// soft deletion of an aggregate.
 func (softDeletedEvent) SoftDelete() bool { return true }
 
 type softRestoredEvent struct{}
 
+// SoftRestore returns true, indicating that the aggregate has been restored
+// from soft deletion.
 func (softRestoredEvent) SoftRestore() bool { return true }

aggregate/snapshot/cleanup/service_test.go

@@ -137,6 +137,9 @@ func TestService_Stop_errNotStarted(t *testing.T) {
 	}
 }
 
+// MarshalSnapshot encodes the mockState of a mockAggregate into a byte slice
+// using gob encoding. It returns the encoded byte slice and an error if the
+// encoding fails.
 func (a *mockAggregate) MarshalSnapshot() ([]byte, error) {
 	var buf bytes.Buffer
 	if err := gob.NewEncoder(&buf).Encode(a.mockState); err != nil {
@@ -145,6 +148,8 @@ func (a *mockAggregate) MarshalSnapshot() ([]byte, error) {
 	return buf.Bytes(), nil
 }
 
+// UnmarshalSnapshot unmarshals a byte slice into the mockState of a
+// mockAggregate using gob decoding. It returns an error if the decoding fails.
 func (a *mockAggregate) UnmarshalSnapshot(p []byte) error {
 	if err := gob.NewDecoder(bytes.NewReader(p)).Decode(&a.mockState); err != nil {
 		return fmt.Errorf("gob: %w", err)

aggregate/snapshot/encode_test.go

@@ -109,6 +109,9 @@ func TestUnmarshal_unmarshaler(t *testing.T) {
 	}
 }
 
+// MarshalSnapshot encodes the mockState of the mockSnapshotter using the gob
+// package and returns the resulting byte slice. Returns an error if encoding
+// fails.
 func (a *mockSnapshotter) MarshalSnapshot() ([]byte, error) {
 	var buf bytes.Buffer
 	if err := gob.NewEncoder(&buf).Encode(a.mockState); err != nil {
@@ -117,6 +120,8 @@ func (a *mockSnapshotter) MarshalSnapshot() ([]byte, error) {
 	return buf.Bytes(), nil
 }
 
+// UnmarshalSnapshot decodes the provided byte slice into the mockState of the
+// mockSnapshotter, using the gob package. Returns an error if decoding fails.
 func (a *mockSnapshotter) UnmarshalSnapshot(p []byte) error {
 	if err := gob.NewDecoder(bytes.NewReader(p)).Decode(&a.mockState); err != nil {
 		return fmt.Errorf("gob: %w", err)

aggregate/stream/benchmark_test.go

@@ -26,86 +26,139 @@ type mockAggregate struct {
 	b string
 }
 
+// BenchmarkStream_10A_1E benchmarks the streaming of events for 10 aggregates
+// with 1 event per aggregate.
 func BenchmarkStream_10A_1E(b *testing.B) {
 	benchmark(b, 10, 1)
 }
 
+// BenchmarkStream_10A_10E runs a benchmark for streaming 10 events for each of
+// 10 aggregates with various options such as grouping and sorting.
 func BenchmarkStream_10A_10E(b *testing.B) {
 	benchmark(b, 10, 10)
 }
 
+// BenchmarkStream_10A_100E benchmarks the performance of streaming 100 events
+// for 10 aggregates with various options such as ungrouped and unsorted,
+// grouped and unsorted, or grouped and sorted.
 func BenchmarkStream_10A_100E(b *testing.B) {
 	benchmark(b, 10, 100)
 }
 
+// BenchmarkStream_10A_1000E benchmarks the stream performance with 10
+// aggregates and 1000 events per aggregate. The benchmark runs ungrouped and
+// unsorted, grouped and unsorted, and grouped and sorted scenarios.
 func BenchmarkStream_10A_1000E(b *testing.B) {
 	benchmark(b, 10, 1000)
 }
 
+// BenchmarkStream_10A_10000E benchmarks the streaming of events for 10
+// aggregates with 10000 events per aggregate, with various grouping and sorting
+// options.
 func BenchmarkStream_10A_10000E(b *testing.B) {
 	benchmark(b, 10, 10000)
 }
 
+// BenchmarkStream_10A_100000E benchmarks the stream function with 10 aggregates
+// and 100,000 events.
 func BenchmarkStream_10A_100000E(b *testing.B) {
 	benchmark(b, 10, 100000)
 }
 
+// BenchmarkStream_100A_1E benchmarks the streaming of events for 100 aggregates
+// with 1 event per aggregate.
 func BenchmarkStream_100A_1E(b *testing.B) {
 	benchmark(b, 100, 1)
 }
 
+// BenchmarkStream_100A_10E benchmarks the performance of streaming 10 events
+// for 100 aggregates with various grouping and sorting options.
 func BenchmarkStream_100A_10E(b *testing.B) {
 	benchmark(b, 100, 10)
 }
 
+// BenchmarkStream_100A_100E benchmarks the performance of streaming 100 events
+// for 100 aggregates with various options such as ungrouped and unsorted,
+// grouped and unsorted, or grouped and sorted.
 func BenchmarkStream_100A_100E(b *testing.B) {
 	benchmark(b, 100, 100)
 }
 
+// BenchmarkStream_100A_1000E benchmarks the stream performance with 100
+// aggregates and 1000 events per aggregate, with various grouping and sorting
+// scenarios.
 func BenchmarkStream_100A_1000E(b *testing.B) {
 	benchmark(b, 100, 1000)
 }
 
+// BenchmarkStream_100A_10000E benchmarks the streaming of events for 100
+// aggregates with 10,000 events per aggregate with various grouping and sorting
+// options.
 func BenchmarkStream_100A_10000E(b *testing.B) {
 	benchmark(b, 100, 10000)
 }
 
+// BenchmarkStream_1000A_1E benchmarks the streaming of events for 1000
+// aggregates with 1 event per aggregate, with options for ungrouped and
+// unsorted, grouped and unsorted, and grouped and sorted streams.
 func BenchmarkStream_1000A_1E(b *testing.B) {
 	benchmark(b, 1000, 1)
 }
 
+// BenchmarkStream_1000A_10E benchmarks the streaming of 10 events for 1000
+// aggregates with various grouping and sorting options.
 func BenchmarkStream_1000A_10E(b *testing.B) {
 	benchmark(b, 1000, 10)
 }
 
+// BenchmarkStream_1000A_100E benchmarks the performance of streaming 100 events
+// for 1000 aggregates with various options such as ungrouped and unsorted,
+// grouped and unsorted, or grouped and sorted.
 func BenchmarkStream_1000A_100E(b *testing.B) {
 	benchmark(b, 1000, 100)
 }
 
+// BenchmarkStream_1000A_1000E benchmarks the performance of streaming 1000
+// events for 1000 aggregates with various options such as ungrouped and
+// unsorted, grouped and unsorted, or grouped and sorted.
 func BenchmarkStream_1000A_1000E(b *testing.B) {
 	benchmark(b, 1000, 1000)
 }
 
+// BenchmarkStream_10000A_1E benchmarks the streaming of one event for 10,000
+// aggregates with various grouping and sorting options.
 func BenchmarkStream_10000A_1E(b *testing.B) {
 	benchmark(b, 10000, 1)
 }
 
+// BenchmarkStream_10000A_10E benchmarks the streaming of events for 10,000
+// aggregates with 10 events per aggregate, with various grouping and sorting
+// options.
 func BenchmarkStream_10000A_10E(b *testing.B) {
 	benchmark(b, 10000, 10)
 }
 
+// BenchmarkStream_10000A_100E benchmarks the performance of streaming 100
+// events for 10,000 aggregates with various grouping and sorting options.
 func BenchmarkStream_10000A_100E(b *testing.B) {
 	benchmark(b, 10000, 100)
 }
 
+// BenchmarkStream_100000A_1E measures the performance of streaming 1 event for
+// 100000 different aggregates with options for grouped and sorted streams.
 func BenchmarkStream_100000A_1E(b *testing.B) {
 	benchmark(b, 100000, 1)
 }
 
+// BenchmarkStream_100000A_10E benchmarks the performance of streaming 10 events
+// for 100,000 different aggregates, with options for grouped and sorted
+// streams.
 func BenchmarkStream_100000A_10E(b *testing.B) {
 	benchmark(b, 100000, 10)
 }
 
+// BenchmarkStream_100000A_100E measures the performance of streaming 100000
+// aggregates with 100 events each.
 func BenchmarkStream_100000A_100E(b *testing.B) {
 	benchmark(b, 100000, 100)
 }
@@ -169,6 +222,8 @@ L:
 	_ = gerr
 }
 
+// ApplyEvent applies an event to the mockAggregate. It updates the state of the
+// mockAggregate according to the event's name.
 func (a *mockAggregate) ApplyEvent(evt event.Event) {
 	for i, name := range names {
 		if name != evt.Name() {

aggregate/stream/stream_test.go

@@ -355,4 +355,6 @@ func makeFactory(am map[uuid.UUID]aggregate.Aggregate) func(string, uuid.UUID) a
 
 type softDeletedEvent struct{}
 
+// SoftDelete marks an aggregate as soft-deleted. When an aggregate is marked as
+// soft-deleted, it will be included in the stream even if it has no events.
 func (softDeletedEvent) SoftDelete() bool { return true }

backend/memory/model_repository_test.go

@@ -135,6 +135,7 @@ type uuidModel struct {
 	Foo string
 }
 
+// ModelID returns the unique identifier of the uuidModel.
 func (m uuidModel) ModelID() uuid.UUID {
 	return m.ID
 }

backend/mongo/model_repository_test.go

@@ -242,6 +242,7 @@ type basicModel struct {
 	Foo string
 }
 
+// ModelID returns the unique identifier of a basicModel instance.
 func (m basicModel) ModelID() primitive.ObjectID {
 	return m.ID
 }
@@ -251,6 +252,9 @@ type uuidModel struct {
 	Foo string
 }
 
+// ModelID returns the unique identifier of a model instance. It does not
+// describe the type of ModelID, but simply returns the unique identifier
+// associated with the instance.
 func (m uuidModel) ModelID() uuid.UUID {
 	return m.ID
 }

codec/registry_test.go

@@ -12,16 +12,23 @@ import (
 	"github.com/modernice/goes/event"
 )
 
+// FooData represents a type that contains a string and an integer, used in
+// testing for encoding and decoding data using different codecs.
 type FooData struct {
 	Foo string
 	Bar int
 }
 
+// BarData is a struct type used to encode and decode binary data for events. It
+// implements methods to Marshal and Unmarshal data, and is registered with a
+// codec.Registry during tests.
 type BarData struct {
 	Foo string
 	Bar int
 }
 
+// Marshal returns the gob-encoded byte slice representation of the BarData
+// value.
 func (data BarData) Marshal() ([]byte, error) {
 	var out bytes.Buffer
 	if err := gob.NewEncoder(&out).Encode(data); err != nil {
@@ -30,6 +37,7 @@ func (data BarData) Marshal() ([]byte, error) {
 	return out.Bytes(), nil
 }
 
+// Unmarshal decodes a byte slice into a BarData value.
 func (data *BarData) Unmarshal(b []byte) error {
 	return gob.NewDecoder(bytes.NewReader(b)).Decode(data)
 }

command/builtin/builtin_test.go

@@ -313,6 +313,7 @@ func newMockAggregate(id uuid.UUID) *mockAggregate {
 	}
 }
 
+// ApplyEvent applies an event to a mockAggregate, updating its state.
 func (ma *mockAggregate) ApplyEvent(evt event.Event) {
 	data := evt.Data().(test.FoobarEventData)
 	ma.Foo += data.A

command/error_test.go

@@ -211,10 +211,13 @@ type errorWithDetails struct {
 	details []*command.ErrDetail
 }
 
+// Error returns the error message for an errorWithDetails instance.
 func (err *errorWithDetails) Error() string {
 	return "error with details"
 }
 
+// Details returns the error details of an errorWithDetails instance as a slice
+// of ErrDetail pointers.
 func (err *errorWithDetails) Details() []*command.ErrDetail {
 	return err.details
 }
@@ -223,10 +226,13 @@ type errorWithCode struct {
 	code errorCode
 }
 
+// Error returns the error message of the underlying error in the errorWithCode
+// receiver.
 func (err *errorWithCode) Error() string {
 	return fmt.Sprintf("error with code %d", err.code)
 }
 
+// Code returns the error code associated with the errorWithCode.
 func (err *errorWithCode) Code() errorCode {
 	return err.code
 }