Add doc links throughout our user-facing APIs (temporalio#1239)

Backfill doc links throughout our user-facing APIs. I didn't touch the
internal package as those aren't supposed to be for external
consumption.

While here I cleaned up a few things, like adding links to referenced
code samples and removing a doc comment in a spot where they're
unsupported; you can't add links in the comments on interface methods or
struct members.

activity/doc.go

@@ -102,7 +102,7 @@ the Temporal managed service.
 	}
 
 When the Activity times out due to a missed heartbeat, the last value of the details (progress in the above sample) is
-returned from the workflow.ExecuteActivity function as the details field of TimeoutError with TimeoutType_HEARTBEAT.
+returned from the [workflow.ExecuteActivity] function as the details field of [temporal.TimeoutError] with TimeoutType_HEARTBEAT.
 
 It is also possible to heartbeat an Activity from an external source:
 
@@ -113,7 +113,7 @@ It is also possible to heartbeat an Activity from an external source:
 	err := client.RecordActivityHeartbeat(ctx, taskToken, details)
 
 It expects an additional parameter, "taskToken", which is the value of the binary "TaskToken" field of the
-"ActivityInfo" struct retrieved inside the Activity (GetActivityInfo(ctx).TaskToken). "details" is the serializable
+[activity.Info] retrieved inside the Activity (GetActivityInfo(ctx).TaskToken). "details" is the serializable
 payload containing progress information.
 
 # Activity Cancellation

client/client.go

@@ -25,6 +25,7 @@
 //go:generate mockgen -copyright_file ../LICENSE -package client -source client.go -destination client_mock.go
 
 // Package client is used by external programs to communicate with Temporal service.
+//
 // NOTE: DO NOT USE THIS API INSIDE OF ANY WORKFLOW CODE!!!
 package client
 
@@ -401,15 +402,13 @@ type (
 		//  - "(WorkflowID = 'wid1' or (WorkflowType = 'type2' and WorkflowID = 'wid2'))".
 		//  - "CloseTime between '2019-08-27T15:04:05+00:00' and '2019-08-28T15:04:05+00:00'".
 		//  - to list only open workflow use "CloseTime is null"
-		// For supported operations on different server versions see [Visibility].
+		// For supported operations on different server versions see https://docs.temporal.io/visibility.
 		// Retrieved workflow executions are sorted by StartTime in descending order when list open workflow,
 		// and sorted by CloseTime in descending order for other queries.
 		// The errors it can return:
 		//  - serviceerror.InvalidArgument
 		//  - serviceerror.Internal
 		//  - serviceerror.Unavailable
-		//
-		// [Visibility]: https://docs.temporal.io/visibility
 		ListWorkflow(ctx context.Context, request *workflowservice.ListWorkflowExecutionsRequest) (*workflowservice.ListWorkflowExecutionsResponse, error)
 
 		// ListArchivedWorkflow gets archived workflow executions based on query. This API will return BadRequest if Temporal
@@ -424,27 +423,23 @@ type (
 
 		// ScanWorkflow gets workflow executions based on query. The query is basically the SQL WHERE clause
 		// (see ListWorkflow for query examples).
-		// For supported operations on different server versions see [Visibility].
+		// For supported operations on different server versions see https://docs.temporal.io/visibility.
 		// ScanWorkflow should be used when retrieving large amount of workflows and order is not needed.
 		// It will use more resources than ListWorkflow, but will be several times faster
 		// when retrieving millions of workflows.
 		// The errors it can return:
 		//  - serviceerror.InvalidArgument
 		//  - serviceerror.Internal
 		//  - serviceerror.Unavailable
-		//
-		// [Visibility]: https://docs.temporal.io/visibility
 		ScanWorkflow(ctx context.Context, request *workflowservice.ScanWorkflowExecutionsRequest) (*workflowservice.ScanWorkflowExecutionsResponse, error)
 
 		// CountWorkflow gets number of workflow executions based on query. The query is basically the SQL WHERE clause
 		// (see ListWorkflow for query examples).
-		// For supported operations on different server versions see [Visibility].
+		// For supported operations on different server versions see https://docs.temporal.io/visibility.
 		// The errors it can return:
 		//  - serviceerror.InvalidArgument
 		//  - serviceerror.Internal
 		//  - serviceerror.Unavailable
-		//
-		// [Visibility]: https://docs.temporal.io/visibility
 		CountWorkflow(ctx context.Context, request *workflowservice.CountWorkflowExecutionsRequest) (*workflowservice.CountWorkflowExecutionsResponse, error)
 
 		// GetSearchAttributes returns valid search attributes keys and value types.
@@ -678,7 +673,7 @@ var (
 	_ internal.NamespaceClient = NamespaceClient(nil)
 )
 
-// NewValue creates a new converter.EncodedValue which can be used to decode binary data returned by Temporal.  For example:
+// NewValue creates a new [converter.EncodedValue] which can be used to decode binary data returned by Temporal.  For example:
 // User had Activity.RecordHeartbeat(ctx, "my-heartbeat") and then got response from calling Client.DescribeWorkflowExecution.
 // The response contains binary field PendingActivityInfo.HeartbeatDetails,
 // which can be decoded by using:
@@ -689,7 +684,7 @@ func NewValue(data *commonpb.Payloads) converter.EncodedValue {
 	return internal.NewValue(data)
 }
 
-// NewValues creates a new converter.EncodedValues which can be used to decode binary data returned by Temporal. For example:
+// NewValues creates a new [converter.EncodedValues] which can be used to decode binary data returned by Temporal. For example:
 // User had Activity.RecordHeartbeat(ctx, "my-heartbeat", 123) and then got response from calling Client.DescribeWorkflowExecution.
 // The response contains binary field PendingActivityInfo.HeartbeatDetails,
 // which can be decoded by using:

contrib/tally/handler.go

@@ -48,7 +48,7 @@ func NewMetricsHandler(scope tally.Scope) client.MetricsHandler {
 }
 
 // ScopeFromHandler returns the underlying scope of the handler. Callers may
-// need to check workflow.IsReplaying(ctx) to avoid recording metrics during
+// need to check [workflow.IsReplaying] to avoid recording metrics during
 // replay. If this handler was not created via this package, [github.com/uber-go/tally.NoopScope] is
 // returned.
 //

interceptor/interceptor.go

@@ -37,12 +37,12 @@ import (
 // calls will be intercepted by it. If an implementation of this interceptor is
 // provided via worker options, all worker calls will be intercepted by it.
 //
-// All implementations of this should embed InterceptorBase but are not required
+// All implementations of this should embed [InterceptorBase] but are not required
 // to.
 type Interceptor = internal.Interceptor
 
 // InterceptorBase is a default implementation of Interceptor meant for
-// embedding. It simply embeds ClientInterceptorBase and WorkerInterceptorBase.
+// embedding. It simply embeds [ClientInterceptorBase] and [WorkerInterceptorBase].
 type InterceptorBase = internal.InterceptorBase
 
 // WorkerInterceptor is an interface for all calls that can be intercepted
@@ -55,9 +55,9 @@ type InterceptorBase = internal.InterceptorBase
 // changes.
 type WorkerInterceptor = internal.WorkerInterceptor
 
-// WorkerInterceptorBase is a default implementation of WorkerInterceptor that
-// simply instantiates ActivityInboundInterceptorBase or
-// WorkflowInboundInterceptorBase when called to intercept activities or
+// WorkerInterceptorBase is a default implementation of [WorkerInterceptor] that
+// simply instantiates [ActivityInboundInterceptorBase] or
+// [WorkflowInboundInterceptorBase] when called to intercept activities or
 // workflows respectively.
 //
 // This must be embedded into all WorkerInterceptor implementations to safely
@@ -69,15 +69,15 @@ type WorkerInterceptorBase = internal.WorkerInterceptorBase
 // activity calls, can change the outbound interceptor in Init before the next
 // call in the chain.
 //
-// All implementations must embed ActivityInboundInterceptorBase to safely
+// All implementations must embed [ActivityInboundInterceptorBase] to safely
 // handle future changes.
 type ActivityInboundInterceptor = internal.ActivityInboundInterceptor
 
 // ActivityInboundInterceptorBase is a default implementation of
-// ActivityInboundInterceptor that forwards calls to the next inbound
+// [ActivityInboundInterceptor] that forwards calls to the next inbound
 // interceptor and uses an ActivityOutboundInterceptorBase on Init.
 //
-// This must be embedded into all ActivityInboundInterceptor implementations to
+// This must be embedded into all [ActivityInboundInterceptor] implementations to
 // safely handle future changes.
 type ActivityInboundInterceptorBase = internal.ActivityInboundInterceptorBase
 
@@ -87,12 +87,12 @@ type ExecuteActivityInput = internal.ExecuteActivityInput
 // ActivityOutboundInterceptor is an interface for all activity calls
 // originating from the SDK.
 //
-// All implementations must embed ActivityOutboundInterceptorBase to safely
+// All implementations must embed [ActivityOutboundInterceptorBase] to safely
 // handle future changes.
 type ActivityOutboundInterceptor = internal.ActivityOutboundInterceptor
 
 // ActivityOutboundInterceptorBase is a default implementation of
-// ActivityOutboundInterceptor that forwards calls to the next outbound
+// [ActivityOutboundInterceptor] that forwards calls to the next outbound
 // interceptor.
 //
 // This must be embedded into all ActivityOutboundInterceptor implementations to
@@ -104,15 +104,15 @@ type ActivityOutboundInterceptorBase = internal.ActivityOutboundInterceptorBase
 // workflow calls, can change the outbound interceptor in Init before the next
 // call in the chain.
 //
-// All implementations must embed WorkflowInboundInterceptorBase to safely
+// All implementations must embed [WorkflowInboundInterceptorBase] to safely
 // handle future changes.
 type WorkflowInboundInterceptor = internal.WorkflowInboundInterceptor
 
 // WorkflowInboundInterceptorBase is a default implementation of
-// WorkflowInboundInterceptor that forwards calls to the next inbound
+// [WorkflowInboundInterceptor] that forwards calls to the next inbound
 // interceptor and uses an WorkflowOutboundInterceptorBase on Init.
 //
-// This must be embedded into all WorkflowInboundInterceptor implementations to
+// This must be embedded into all [WorkflowInboundInterceptor] implementations to
 // safely handle future changes.
 type WorkflowInboundInterceptorBase = internal.WorkflowInboundInterceptorBase
 
@@ -134,47 +134,47 @@ type UpdateInput = internal.UpdateInput
 // WorkflowOutboundInterceptor is an interface for all workflow calls
 // originating from the SDK.
 //
-// All implementations must embed WorkflowOutboundInterceptorBase to safely
+// All implementations must embed [WorkflowOutboundInterceptorBase] to safely
 // handle future changes.
 type WorkflowOutboundInterceptor = internal.WorkflowOutboundInterceptor
 
 // WorkflowOutboundInterceptorBase is a default implementation of
-// WorkflowOutboundInterceptor that forwards calls to the next outbound
+// [WorkflowOutboundInterceptor] that forwards calls to the next outbound
 // interceptor.
 //
-// This must be embedded into all WorkflowOutboundInterceptor implementations to
+// This must be embedded into all [WorkflowOutboundInterceptor] implementations to
 // safely handle future changes.
 type WorkflowOutboundInterceptorBase = internal.WorkflowOutboundInterceptorBase
 
-// ClientInterceptor for providing a ClientOutboundInterceptor to intercept
+// ClientInterceptor for providing a [ClientOutboundInterceptor] to intercept
 // certain workflow-specific client calls from the SDK. If an implementation of
 // this is provided via client or worker options, certain client calls will be
 // intercepted by it.
 //
-// All implementations must embed ClientInterceptorBase to safely handle future
+// All implementations must embed [ClientInterceptorBase] to safely handle future
 // changes.
 type ClientInterceptor = internal.ClientInterceptor
 
-// ClientInterceptorBase is a default implementation of ClientInterceptor that
-// simply instantiates ClientOutboundInterceptorBase when called to intercept
+// ClientInterceptorBase is a default implementation of [ClientInterceptor] that
+// simply instantiates [ClientOutboundInterceptorBase] when called to intercept
 // the client.
 //
-// This must be embedded into all ClientInterceptor implementations to safely
+// This must be embedded into all [ClientInterceptor] implementations to safely
 // handle future changes.
 type ClientInterceptorBase = internal.ClientInterceptorBase
 
 // ClientOutboundInterceptor is an interface for certain workflow-specific calls
 // originating from the SDK.
 //
-// All implementations must embed ClientOutboundInterceptorBase to safely handle
+// All implementations must embed [ClientOutboundInterceptorBase] to safely handle
 // future changes.
 type ClientOutboundInterceptor = internal.ClientOutboundInterceptor
 
 // ClientOutboundInterceptorBase is a default implementation of
-// ClientOutboundInterceptor that forwards calls to the next outbound
+// [ClientOutboundInterceptor] that forwards calls to the next outbound
 // interceptor.
 //
-// This must be embedded into all ActivityInboundInterceptor implementations to
+// This must be embedded into all [ClientOutboundInterceptor] implementations to
 // safely handle future changes.
 type ClientOutboundInterceptorBase = internal.ClientOutboundInterceptorBase
 

interceptor/tracing_interceptor.go

@@ -100,7 +100,7 @@ type TracerOptions struct {
 	// never be nil.
 	//
 	// This is used internally to set the span on contexts not natively supported
-	// by tracing systems such as workflow.Context.
+	// by tracing systems such as [workflow.Context].
 	SpanContextKey interface{}
 
 	// HeaderKey is the key name on the Temporal header to serialize the span to.

temporal/doc.go

@@ -47,7 +47,7 @@ The root temporal package contains common data structures. The subpackages are:
     activity code.
   - testsuite - unit testing framework for activity and workflow testing
 
-How Temporal works
+# How Temporal works
 
 The Temporal hosted service brokers and persists events generated during workflow execution. Worker nodes owned and
 operated by customers execute the coordination and task logic. To facilitate the implementation of worker nodes Temporal
@@ -56,7 +56,7 @@ provides a client-side library for the Go language.
 In Temporal, you can code the logical flow of events separately as a workflow and code business logic as activities. The
 workflow identifies the activities and sequences them, while an activity executes the logic.
 
-Key Features
+# Key Features
 
 Dynamic workflow execution graphs - Determine the workflow execution graphs at runtime based on the data you are
 processing. Temporal does not pre-compute the execution graphs at compile time or at workflow start time. Therefore, you

worker/worker.go

@@ -78,7 +78,7 @@ type (
 	// WorkflowRegistry exposes workflow registration functions to consumers.
 	WorkflowRegistry interface {
 		// RegisterWorkflow - registers a workflow function with the worker.
-		// A workflow takes a workflow.Context and input and returns a (result, error) or just error.
+		// A workflow takes a [workflow.Context] and input and returns a (result, error) or just error.
 		// Examples:
 		//	func sampleWorkflow(ctx workflow.Context, input []byte) (result []byte, err error)
 		//	func sampleWorkflow(ctx workflow.Context, arg1 int, arg2 string) (result []byte, err error)
@@ -155,7 +155,7 @@ type (
 	// For example if a workflow failed in production then its history can be downloaded through UI or CLI
 	// and replayed in a debugger as many times as necessary.
 	// Use this class to create unit tests that check if workflow changes are backwards compatible.
-	// It is important to maintain backwards compatibility through use of workflow.GetVersion
+	// It is important to maintain backwards compatibility through use of [workflow.GetVersion]
 	// to ensure that new deployments are not going to break open workflows.
 	WorkflowReplayer interface {
 		// RegisterWorkflow registers workflow that is going to be replayed
@@ -206,7 +206,7 @@ type (
 
 	// WorkflowPanicPolicy is used for configuring how worker deals with workflow
 	// code panicking which includes non backwards compatible changes to the workflow code without appropriate
-	// versioning (see workflow.GetVersion).
+	// versioning (see [workflow.GetVersion]).
 	// The default behavior is to block workflow execution until the problem is fixed.
 	WorkflowPanicPolicy = internal.WorkflowPanicPolicy
 

workflow/deterministic_wrappers.go

@@ -33,8 +33,8 @@ import (
 type (
 
 	// Channel must be used instead of a native go channel by workflow code.
-	// Use workflow.NewChannel(ctx) method to create a Channel instance.
-	// Channel extends both ReadChannel and SendChannel. Prefer using one of these interfaces
+	// Use [workflow.NewChannel] to create a Channel instance.
+	// Channel extends both [ReceiveChannel] and [SendChannel]. Prefer using one of these interfaces
 	// to share a Channel with consumers or producers.
 	Channel = internal.Channel
 
@@ -45,14 +45,14 @@ type (
 	SendChannel = internal.SendChannel
 
 	// Selector must be used instead of native go select by workflow code.
-	// Use workflow.NewSelector(ctx) method to create a Selector instance.
+	// Use [workflow.NewSelector] method to create a Selector instance.
 	Selector = internal.Selector
 
 	// Future represents the result of an asynchronous computation.
 	Future = internal.Future
 
 	// Settable is used to set value or error on a future.
-	// See more: workflow.NewFuture(ctx).
+	// See more: [workflow.NewFuture].
 	Settable = internal.Settable
 
 	// WaitGroup is used to wait for a collection of