Improve documentation for workflow package

cschleiden · cschleiden · commit 9231003ce57b · 2023-09-22T22:13:01.000-07:00
diff --git a/internal/workflow/executor_test.go b/internal/workflow/executor_test.go
@@ -282,7 +282,7 @@ func Test_Executor(t *testing.T) {
 						sync.Await[int](f1, func(ctx sync.Context, f sync.Future[int]) {
 							workflowWithSelectorHits++
 						}),
-						sync.Await[struct{}](t, func(ctx sync.Context, _ sync.Future[struct{}]) {
+						sync.Await[any](t, func(ctx sync.Context, _ sync.Future[any]) {
 							workflowWithSelectorHits++
 						}),
 					)
diff --git a/samples/timer/timer.go b/samples/timer/timer.go
@@ -73,7 +73,7 @@ func Workflow1(ctx workflow.Context, msg string) (string, error) {
 
 	workflow.Select(
 		ctx,
-		workflow.Await(workflow.ScheduleTimer(tctx, 2*time.Second), func(ctx workflow.Context, f workflow.Future[struct{}]) {
+		workflow.Await(workflow.ScheduleTimer(tctx, 2*time.Second), func(ctx workflow.Context, f workflow.Future[any]) {
 			if _, err := f.Get(ctx); err != nil {
 				logger.Debug("Timer canceled")
 			} else {
diff --git a/tester/tester_activity_test.go b/tester/tester_activity_test.go
@@ -24,7 +24,7 @@ func Test_Activity_Long(t *testing.T) {
 
 		workflow.Select(ctx,
 			// Fire timer before `activity1` completes
-			workflow.Await(workflow.ScheduleTimer(tctx, time.Millisecond*100), func(ctx workflow.Context, f workflow.Future[struct{}]) {
+			workflow.Await(workflow.ScheduleTimer(tctx, time.Millisecond*100), func(ctx workflow.Context, f workflow.Future[any]) {
 				// Timer fired
 				r = "timer"
 			}),
diff --git a/tester/tester_timers_test.go b/tester/tester_timers_test.go
@@ -109,11 +109,11 @@ func timerCancellationSubWorkflow(ctx workflow.Context) error {
 
 	workflow.Select(
 		ctx,
-		workflow.Await(t, func(ctx workflow.Context, f workflow.Future[struct{}]) {
+		workflow.Await(t, func(ctx workflow.Context, _ workflow.Future[any]) {
 			// Cancel t2
 			cancel()
 		}),
-		workflow.Await(t2, func(ctx workflow.Context, f workflow.Future[struct{}]) {
+		workflow.Await(t2, func(ctx workflow.Context, _ workflow.Future[any]) {
 			// do nothing here, should never fire
 			panic("timer should have been cancelled")
 		}),
diff --git a/workflow/channel.go b/workflow/channel.go
@@ -3,21 +3,30 @@ package workflow
 import "github.com/cschleiden/go-workflows/internal/sync"
 
 type Channel[T any] interface {
+	// Send sends a value to the channel. If the channel is closed, this will panic.
 	Send(ctx Context, v T)
 
+	// SendNonblocking sends a value to the channel. This call is non-blocking and will return whether the
+	// value could be sent. If the channel is closed, this will panic
 	SendNonblocking(v T) (ok bool)
 
+	// Receive receives a value from the channel.
 	Receive(ctx Context) (v T, ok bool)
 
+	// ReceiveNonBlocking tries to receives a value from the channel. This call is non-blocking and will return
+	// whether the value could be returned.
 	ReceiveNonBlocking() (v T, ok bool)
 
+	// Close closes the channel. This will cause all future send operations to panic.
 	Close()
 }
 
+// NewChannel creates a new channel.
 func NewChannel[T any]() Channel[T] {
 	return sync.NewChannel[T]()
 }
 
+// NewBufferedChannel creates a new buffered channel with the given size.
 func NewBufferedChannel[T any](size int) Channel[T] {
 	return sync.NewBufferedChannel[T](size)
 }
diff --git a/workflow/context.go b/workflow/context.go
@@ -31,6 +31,8 @@ func WithValue(parent Context, key, val interface{}) Context {
 	return sync.WithValue(parent, key, val)
 }
 
+// NewDisconnectedContext creates a new context that is disconnected from any parent
+// context.
 func NewDisconnectedContext(ctx Context) Context {
 	return sync.NewDisconnectedContext(ctx)
 }
diff --git a/workflow/continueasnew.go b/workflow/continueasnew.go
@@ -9,8 +9,8 @@ import (
 	"github.com/cschleiden/go-workflows/internal/continueasnew"
 )
 
-// ContinueAsNew restarts the current workflow with the given arguments
-func ContinueAsNew(ctx Context, args ...interface{}) error {
+// ContinueAsNew restarts the current workflow with the given arguments.
+func ContinueAsNew(ctx Context, args ...any) error {
 	// Capture context
 	propagators := propagators(ctx)
 	metadata := &metadata.WorkflowMetadata{}
diff --git a/workflow/instance.go b/workflow/instance.go
@@ -4,6 +4,7 @@ import (
 	"github.com/cschleiden/go-workflows/internal/workflowstate"
 )
 
+// WorkflowInstance returns the current workflow instance.
 func WorkflowInstance(ctx Context) *Instance {
 	wfState := workflowstate.WorkflowState(ctx)
 	return wfState.Instance()
diff --git a/workflow/logger.go b/workflow/logger.go
@@ -6,6 +6,7 @@ import (
 	"github.com/cschleiden/go-workflows/internal/workflowstate"
 )
 
+// Logger returns the logger for the current workflow.
 func Logger(ctx Context) *slog.Logger {
 	wfState := workflowstate.WorkflowState(ctx)
 	return wfState.Logger()
diff --git a/workflow/now.go b/workflow/now.go
@@ -6,6 +6,7 @@ import (
 	"github.com/cschleiden/go-workflows/internal/workflowstate"
 )
 
+// Now returns the current time.
 func Now(ctx Context) time.Time {
 	wfState := workflowstate.WorkflowState(ctx)
 	return wfState.Time()
diff --git a/workflow/replaying.go b/workflow/replaying.go
@@ -4,6 +4,7 @@ import (
 	"github.com/cschleiden/go-workflows/internal/workflowstate"
 )
 
+// Replaying returns true if the current workflow execution is replaying or not.
 func Replaying(ctx Context) bool {
 	wfState := workflowstate.WorkflowState(ctx)
 	return wfState.Replaying()
diff --git a/workflow/retries.go b/workflow/retries.go
@@ -30,6 +30,7 @@ var DefaultRetryOptions = RetryOptions{
 	BackoffCoefficient: 1,
 }
 
+// WithRetries executes the given function with retries.
 func WithRetries[T any](ctx Context, retryOptions RetryOptions, fn func(ctx Context, attempt int) Future[T]) Future[T] {
 	attempt := 0
 	firstAttempt := Now(ctx)
diff --git a/workflow/sideeffect.go b/workflow/sideeffect.go
@@ -8,6 +8,11 @@ import (
 	"github.com/cschleiden/go-workflows/internal/workflowtracer"
 )
 
+// SideEffect executes the given function and returns a future that will be resolved with the result of
+// the function.
+//
+// In contrast to Activities, SideEffects are executed inline with the workflow code. They should only
+// be used for short and inexpensive operations. For longer operations, consider using an Activity.
 func SideEffect[TResult any](ctx Context, f func(ctx Context) TResult) Future[TResult] {
 	ctx, span := workflowtracer.Tracer(ctx).Start(ctx, "SideEffect")
 	defer span.End()
diff --git a/workflow/signal.go b/workflow/signal.go
@@ -6,11 +6,13 @@ import (
 	"github.com/cschleiden/go-workflows/internal/workflowtracer"
 )
 
+// NewSignalChannel returns a new signal channel.
 func NewSignalChannel[T any](ctx Context, name string) Channel[T] {
 	wfState := workflowstate.WorkflowState(ctx)
 	return workflowstate.GetSignalChannel[T](ctx, wfState, name)
 }
 
+// SignalWorkflow sends a signal to another running workflow instance.
 func SignalWorkflow[T any](ctx Context, instanceID string, name string, arg T) Future[any] {
 	ctx, span := workflowtracer.Tracer(ctx).Start(ctx, "SignalWorkflow")
 	defer span.End()
diff --git a/workflow/sleep.go b/workflow/sleep.go
@@ -9,6 +9,7 @@ import (
 	"go.opentelemetry.io/otel/trace"
 )
 
+// Sleep sleeps for the given duration.
 func Sleep(ctx Context, d time.Duration) error {
 	ctx, span := workflowtracer.Tracer(ctx).Start(ctx, "Sleep",
 		trace.WithAttributes(attribute.Int64(log.DurationKey, int64(d/time.Millisecond))))
diff --git a/workflow/subworkflow.go b/workflow/subworkflow.go
@@ -33,13 +33,14 @@ var (
 	}
 )
 
-func CreateSubWorkflowInstance[TResult any](ctx Context, options SubWorkflowOptions, workflow interface{}, args ...interface{}) Future[TResult] {
+// CreateSubWorkflowInstance creates a new sub-workflow instance of the given workflow.
+func CreateSubWorkflowInstance[TResult any](ctx Context, options SubWorkflowOptions, workflow Workflow, args ...any) Future[TResult] {
 	return WithRetries(ctx, options.RetryOptions, func(ctx Context, attempt int) Future[TResult] {
 		return createSubWorkflowInstance[TResult](ctx, options, attempt, workflow, args...)
 	})
 }
 
-func createSubWorkflowInstance[TResult any](ctx Context, options SubWorkflowOptions, attempt int, wf interface{}, args ...interface{}) Future[TResult] {
+func createSubWorkflowInstance[TResult any](ctx Context, options SubWorkflowOptions, attempt int, wf Workflow, args ...any) Future[TResult] {
 	f := sync.NewFuture[TResult]()
 
 	// If the context is already canceled, return immediately.
diff --git a/workflow/sync.go b/workflow/sync.go
@@ -11,11 +11,12 @@ type (
 
 var Canceled = sync.Canceled
 
+// NewWaitGroup creates a new WaitGroup instance.
 func NewWaitGroup() WaitGroup {
 	return sync.NewWaitGroup()
 }
 
-// Go spawns a workflow goroutine
+// Go spawns a workflow "goroutine".
 func Go(ctx Context, f func(ctx Context)) {
 	sync.Go(ctx, f)
 }
diff --git a/workflow/timer.go b/workflow/timer.go
@@ -13,8 +13,9 @@ import (
 	"go.opentelemetry.io/otel/trace"
 )
 
-func ScheduleTimer(ctx Context, delay time.Duration) Future[struct{}] {
-	f := sync.NewFuture[struct{}]()
+// ScheduleTimer schedules a timer to fire after the given delay.
+func ScheduleTimer(ctx Context, delay time.Duration) Future[any] {
+	f := sync.NewFuture[any]()
 
 	// If the context is already canceled, return immediately.
 	if ctx.Err() != nil {
@@ -38,7 +39,7 @@ func ScheduleTimer(ctx Context, delay time.Duration) Future[struct{}] {
 			// Remove the timer future from the workflow state and mark it as canceled if it hasn't already fired. This is different
 			// from subworkflow behavior, where we want to wait for the subworkflow to complete before proceeding. Here we can
 			// continue right away.
-			if fi, ok := f.(sync.FutureInternal[struct{}]); ok {
+			if fi, ok := f.(sync.FutureInternal[any]); ok {
 				if !fi.Ready() {
 					wfState.RemoveFuture(scheduleEventID)
 					f.Set(v, Canceled)
diff --git a/workflow/tracer.go b/workflow/tracer.go
@@ -9,6 +9,7 @@ type Span interface {
 	End()
 }
 
+// Tracer creates a the workflow tracer.
 func Tracer(ctx Context) *WorkflowTracer {
 	return &WorkflowTracer{
 		t: workflowtracer.Tracer(ctx),
@@ -19,6 +20,7 @@ type WorkflowTracer struct {
 	t *workflowtracer.WorkflowTracer
 }
 
+// Start starts a new span.
 func (wt *WorkflowTracer) Start(ctx Context, name string, opts ...trace.SpanStartOption) (Context, Span) {
 	ctx, span := wt.t.Start(ctx, name, opts...)
 
diff --git a/workflow/workflow.go b/workflow/workflow.go
@@ -6,8 +6,13 @@ import (
 )
 
 type (
+	// Instance represents a workflow instance.
 	Instance = core.WorkflowInstance
+
+	// Metadata represents the metadata of a workflow instance.
 	Metadata = metadata.WorkflowMetadata
-	Activity = interface{}
+
 	Workflow = interface{}
+
+	Activity = interface{}
 )

Original file line number	Diff line number	Diff line change
`@@ -282,7 +282,7 @@ func Test_Executor(t *testing.T) {`
`282`	`282`	`sync.Await[int](f1, func(ctx sync.Context, f sync.Future[int]) {`
`283`	`283`	`workflowWithSelectorHits++`
`284`	`284`	`}),`
`285`		`- sync.Await[struct{}](t, func(ctx sync.Context, _ sync.Future[struct{}]) {`
	`285`	`+ sync.Await[any](t, func(ctx sync.Context, _ sync.Future[any]) {`
`286`	`286`	`workflowWithSelectorHits++`
`287`	`287`	`}),`
`288`	`288`	`)`
Original file line number	Diff line number	Diff line change
`@@ -31,6 +31,8 @@ func WithValue(parent Context, key, val interface{}) Context {`
`31`	`31`	`return sync.WithValue(parent, key, val)`
`32`	`32`	`}`
`33`	`33`
	`34`	`+// NewDisconnectedContext creates a new context that is disconnected from any parent`
	`35`	`+// context.`
`34`	`36`	`func NewDisconnectedContext(ctx Context) Context {`
`35`	`37`	`return sync.NewDisconnectedContext(ctx)`
`36`	`38`	`}`
Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@ import (`
`4`	`4`	`"github.com/cschleiden/go-workflows/internal/workflowstate"`
`5`	`5`	`)`
`6`	`6`
	`7`	`+// WorkflowInstance returns the current workflow instance.`
`7`	`8`	`func WorkflowInstance(ctx Context) *Instance {`
`8`	`9`	`wfState := workflowstate.WorkflowState(ctx)`
`9`	`10`	`return wfState.Instance()`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@ import (`
`6`	`6`	`"github.com/cschleiden/go-workflows/internal/workflowstate"`
`7`	`7`	`)`
`8`	`8`
	`9`	`+// Logger returns the logger for the current workflow.`
`9`	`10`	`func Logger(ctx Context) *slog.Logger {`
`10`	`11`	`wfState := workflowstate.WorkflowState(ctx)`
`11`	`12`	`return wfState.Logger()`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@ import (`
`6`	`6`	`"github.com/cschleiden/go-workflows/internal/workflowstate"`
`7`	`7`	`)`
`8`	`8`
	`9`	`+// Now returns the current time.`
`9`	`10`	`func Now(ctx Context) time.Time {`
`10`	`11`	`wfState := workflowstate.WorkflowState(ctx)`
`11`	`12`	`return wfState.Time()`