Update Godoc for internal structs/funcs to clarify the package they are exposed under (#1735)

* identify public fields and map to internal fields

* Implemented doclink, added check to CI. Once CI fails, will run with -fix flag

* fix check errors, run -fix with doclink tool

* use doclink's to make objects clickable, fix whitespace issue

* handle windows backwards slash

* Use ast.IsExported

Author: yuandrew

internal/activity.go

@@ -39,11 +39,15 @@ import (
 
 type (
 	// ActivityType identifies an activity type.
+	//
+	// Exposed as: [go.temporal.io/sdk/activity.Type]
 	ActivityType struct {
 		Name string
 	}
 
 	// ActivityInfo contains information about a currently executing activity.
+	//
+	// Exposed as: [go.temporal.io/sdk/activity.Info]
 	ActivityInfo struct {
 		TaskToken         []byte
 		WorkflowType      *WorkflowType
@@ -61,6 +65,8 @@ type (
 	}
 
 	// RegisterActivityOptions consists of options for registering an activity.
+	//
+	// Exposed as: [go.temporal.io/sdk/activity.RegisterOptions]
 	RegisterActivityOptions struct {
 		// When an activity is a function the name is an actual activity type name.
 		// When an activity is part of a structure then each member of the structure becomes an activity with
@@ -81,6 +87,8 @@ type (
 	// ActivityOptions stores all activity-specific parameters that will be stored inside of a context.
 	// The current timeout resolution implementation is in seconds and uses math.Ceil(d.Seconds()) as the duration. But is
 	// subjected to change in the future.
+	//
+	// Exposed as: [go.temporal.io/sdk/workflow.ActivityOptions]
 	ActivityOptions struct {
 		// TaskQueue - Name of the task queue that the activity needs to be scheduled on.
 		// Optional: The default task queue with the same name as the workflow task queue.
@@ -160,6 +168,8 @@ type (
 	}
 
 	// LocalActivityOptions stores local activity specific parameters that will be stored inside of a context.
+	//
+	// Exposed as: [go.temporal.io/sdk/workflow.LocalActivityOptions]
 	LocalActivityOptions struct {
 		// ScheduleToCloseTimeout - The end to end timeout for the local activity, including retries.
 		// At least one of ScheduleToCloseTimeout or StartToCloseTimeout is required.
@@ -179,16 +189,22 @@ type (
 )
 
 // GetActivityInfo returns information about the currently executing activity.
+//
+// Exposed as: [go.temporal.io/sdk/activity.GetInfo]
 func GetActivityInfo(ctx context.Context) ActivityInfo {
 	return getActivityOutboundInterceptor(ctx).GetInfo(ctx)
 }
 
 // HasHeartbeatDetails checks if there are heartbeat details from last attempt.
+//
+// Exposed as: [go.temporal.io/sdk/activity.HasHeartbeatDetails]
 func HasHeartbeatDetails(ctx context.Context) bool {
 	return getActivityOutboundInterceptor(ctx).HasHeartbeatDetails(ctx)
 }
 
 // IsActivity checks if the context is an activity context from a normal or local activity.
+//
+// Exposed as: [go.temporal.io/sdk/activity.IsActivity]
 func IsActivity(ctx context.Context) bool {
 	a := ctx.Value(activityInterceptorContextKey)
 	return a != nil
@@ -202,16 +218,22 @@ func IsActivity(ctx context.Context) bool {
 //
 // Note: Values should not be reused for extraction here because merging on top
 // of existing values may result in unexpected behavior similar to json.Unmarshal.
+//
+// Exposed as: [go.temporal.io/sdk/activity.GetHeartbeatDetails]
 func GetHeartbeatDetails(ctx context.Context, d ...interface{}) error {
 	return getActivityOutboundInterceptor(ctx).GetHeartbeatDetails(ctx, d...)
 }
 
 // GetActivityLogger returns a logger that can be used in the activity.
+//
+// Exposed as: [go.temporal.io/sdk/activity.GetLogger]
 func GetActivityLogger(ctx context.Context) log.Logger {
 	return getActivityOutboundInterceptor(ctx).GetLogger(ctx)
 }
 
 // GetActivityMetricsHandler returns a metrics handler that can be used in the activity.
+//
+// Exposed as: [go.temporal.io/sdk/activity.GetMetricsHandler]
 func GetActivityMetricsHandler(ctx context.Context) metrics.Handler {
 	return getActivityOutboundInterceptor(ctx).GetMetricsHandler(ctx)
 }
@@ -220,6 +242,8 @@ func GetActivityMetricsHandler(ctx context.Context) metrics.Handler {
 // When the worker is stopping, it will close this channel and wait until the worker stop timeout finishes. After the timeout
 // hits, the worker will cancel the activity context and then exit. The timeout can be defined by worker option: WorkerStopTimeout.
 // Use this channel to handle a graceful activity exit when the activity worker stops.
+//
+// Exposed as: [go.temporal.io/sdk/activity.GetWorkerStopChannel]
 func GetWorkerStopChannel(ctx context.Context) <-chan struct{} {
 	return getActivityOutboundInterceptor(ctx).GetWorkerStopChannel(ctx)
 }
@@ -234,6 +258,8 @@ func GetWorkerStopChannel(ctx context.Context) <-chan struct{} {
 //
 // details - The details that you provided here can be seen in the workflow when it receives TimeoutError. You
 // can check error TimeoutType()/Details().
+//
+// Exposed as: [go.temporal.io/sdk/activity.RecordHeartbeat]
 func RecordActivityHeartbeat(ctx context.Context, details ...interface{}) {
 	getActivityOutboundInterceptor(ctx).RecordHeartbeat(ctx, details...)
 }

internal/client.go

@@ -47,14 +47,20 @@ import (
 
 const (
 	// DefaultNamespace is the namespace name which is used if not passed with options.
+	//
+	// Exposed as: [go.temporal.io/sdk/client.DefaultNamespace]
 	DefaultNamespace = "default"
 
 	// QueryTypeStackTrace is the build in query type for Client.QueryWorkflow() call. Use this query type to get the call
 	// stack of the workflow. The result will be a string encoded in the EncodedValue.
+	//
+	// Exposed as: [go.temporal.io/sdk/client.QueryTypeStackTrace]
 	QueryTypeStackTrace string = "__stack_trace"
 
 	// QueryTypeOpenSessions is the build in query type for Client.QueryWorkflow() call. Use this query type to get all open
 	// sessions in the workflow. The result will be a list of SessionInfo encoded in the EncodedValue.
+	//
+	// Exposed as: [go.temporal.io/sdk/client.QueryTypeOpenSessions]
 	QueryTypeOpenSessions string = "__open_sessions"
 
 	// QueryTypeWorkflowMetadata is the query name for the workflow metadata.
@@ -430,6 +436,8 @@ type (
 	}
 
 	// ClientOptions are optional parameters for Client creation.
+	//
+	// Exposed as: [go.temporal.io/sdk/client.Options]
 	ClientOptions struct {
 		// Optional: To set the host:port for this client to connect to.
 		// default: localhost:7233
@@ -516,6 +524,8 @@ type (
 	// CloudOperationsClientOptions are parameters for CloudOperationsClient creation.
 	//
 	// WARNING: Cloud operations client is currently experimental.
+	//
+	// Exposed as: [go.temporal.io/sdk/client.CloudOperationsClientOptions]
 	CloudOperationsClientOptions struct {
 		// Optional: The credentials for this client. This is essentially required.
 		// See [go.temporal.io/sdk/client.NewAPIKeyStaticCredentials],
@@ -562,6 +572,8 @@ type (
 	}
 
 	// ConnectionOptions is provided by SDK consumers to control optional connection params.
+	//
+	// Exposed as: [go.temporal.io/sdk/client.ConnectionOptions]
 	ConnectionOptions struct {
 		// TLS configures connection level security credentials.
 		TLS *tls.Config
@@ -622,6 +634,8 @@ type (
 	// StartWorkflowOptions configuration parameters for starting a workflow execution.
 	// The current timeout resolution implementation is in seconds and uses math.Ceil(d.Seconds()) as the duration. But is
 	// subjected to change in the future.
+	//
+	// Exposed as: [go.temporal.io/sdk/client.StartWorkflowOptions]
 	StartWorkflowOptions struct {
 		// ID - The business identifier of the workflow execution.
 		// Optional: defaulted to a uuid.
@@ -779,6 +793,8 @@ type (
 	// started time. Because of that, to check an activity has started or not, you cannot rely on history events. Instead,
 	// you can use CLI to describe the workflow to see the status of the activity:
 	//     tctl --ns <namespace> wf desc -w <wf-id>
+	//
+	// Exposed as: [go.temporal.io/sdk/temporal.RetryPolicy]
 	RetryPolicy struct {
 		// Backoff interval for the first retry. If BackoffCoefficient is 1.0 then it is used for all retries.
 		// If not set or set to 0, a default interval of 1s will be used.
@@ -840,19 +856,25 @@ type (
 )
 
 // Credentials are optional credentials that can be specified in ClientOptions.
+//
+// Exposed as: [go.temporal.io/sdk/client.Credentials]
 type Credentials interface {
 	applyToOptions(*ConnectionOptions) error
 	// Can return nil to have no interceptor
 	gRPCInterceptor() grpc.UnaryClientInterceptor
 }
 
 // DialClient creates a client and attempts to connect to the server.
+//
+// Exposed as: [go.temporal.io/sdk/client.DialContext]
 func DialClient(ctx context.Context, options ClientOptions) (Client, error) {
 	options.ConnectionOptions.disableEagerConnection = false
 	return NewClient(ctx, options)
 }
 
 // NewLazyClient creates a client and does not attempt to connect to the server.
+//
+// Exposed as: [go.temporal.io/sdk/client.NewLazyClient]
 func NewLazyClient(options ClientOptions) (Client, error) {
 	options.ConnectionOptions.disableEagerConnection = true
 	return NewClient(context.Background(), options)
@@ -861,12 +883,16 @@ func NewLazyClient(options ClientOptions) (Client, error) {
 // NewClient creates an instance of a workflow client
 //
 // Deprecated: Use DialClient or NewLazyClient instead.
+//
+// Exposed as: [go.temporal.io/sdk/client.NewClient]
 func NewClient(ctx context.Context, options ClientOptions) (Client, error) {
 	return newClient(ctx, options, nil)
 }
 
 // NewClientFromExisting creates a new client using the same connection as the
 // existing client.
+//
+// Exposed as: [go.temporal.io/sdk/client.NewClientFromExistingWithContext]
 func NewClientFromExisting(ctx context.Context, existingClient Client, options ClientOptions) (Client, error) {
 	existing, _ := existingClient.(*WorkflowClient)
 	if existing == nil {
@@ -1012,6 +1038,8 @@ func NewServiceClient(workflowServiceClient workflowservice.WorkflowServiceClien
 
 // DialCloudOperationsClient creates a cloud client to perform cloud-management
 // operations.
+//
+// Exposed as: [go.temporal.io/sdk/client.DialCloudOperationsClient]
 func DialCloudOperationsClient(ctx context.Context, options CloudOperationsClientOptions) (CloudOperationsClient, error) {
 	// Set defaults
 	if options.MetricsHandler == nil {
@@ -1089,6 +1117,8 @@ func (op *withStartWorkflowOperationImpl) set(workflowRun WorkflowRun, err error
 }
 
 // NewNamespaceClient creates an instance of a namespace client, to manager lifecycle of namespaces.
+//
+// Exposed as: [go.temporal.io/sdk/client.NewNamespaceClient]
 func NewNamespaceClient(options ClientOptions) (NamespaceClient, error) {
 	// Initialize root tags
 	if options.MetricsHandler == nil {
@@ -1129,6 +1159,8 @@ func newNamespaceServiceClient(workflowServiceClient workflowservice.WorkflowSer
 //
 //	var result string // This need to be same type as the one passed to RecordHeartbeat
 //	NewValue(data).Get(&result)
+//
+// Exposed as: [go.temporal.io/sdk/client.NewValue]
 func NewValue(data *commonpb.Payloads) converter.EncodedValue {
 	return newEncodedValue(data, nil)
 }
@@ -1141,16 +1173,20 @@ func NewValue(data *commonpb.Payloads) converter.EncodedValue {
 //	var result1 string
 //	var result2 int // These need to be same type as those arguments passed to RecordHeartbeat
 //	NewValues(data).Get(&result1, &result2)
+//
+// Exposed as: [go.temporal.io/sdk/client.NewValues]
 func NewValues(data *commonpb.Payloads) converter.EncodedValues {
 	return newEncodedValues(data, nil)
 }
 
 type apiKeyCredentials func(context.Context) (string, error)
 
+// Exposed as: [go.temporal.io/sdk/client.NewAPIKeyStaticCredentials]
 func NewAPIKeyStaticCredentials(apiKey string) Credentials {
 	return NewAPIKeyDynamicCredentials(func(ctx context.Context) (string, error) { return apiKey, nil })
 }
 
+// Exposed as: [go.temporal.io/sdk/client.NewAPIKeyDynamicCredentials]
 func NewAPIKeyDynamicCredentials(apiKeyCallback func(context.Context) (string, error)) Credentials {
 	return apiKeyCredentials(apiKeyCallback)
 }
@@ -1181,6 +1217,7 @@ func (a apiKeyCredentials) gRPCIntercept(
 
 type mTLSCredentials tls.Certificate
 
+// Exposed as: [go.temporal.io/sdk/client.NewMTLSCredentials]
 func NewMTLSCredentials(certificate tls.Certificate) Credentials { return mTLSCredentials(certificate) }
 
 func (m mTLSCredentials) applyToOptions(opts *ConnectionOptions) error {
@@ -1198,11 +1235,15 @@ func (mTLSCredentials) gRPCInterceptor() grpc.UnaryClientInterceptor { return ni
 // WorkflowUpdateServiceTimeoutOrCanceledError is an error that occurs when an update call times out or is cancelled.
 //
 // Note, this is not related to any general concept of timing out or cancelling a running update, this is only related to the client call itself.
+//
+// Exposed as: [go.temporal.io/sdk/client.WorkflowUpdateServiceTimeoutOrCanceledError]
 type WorkflowUpdateServiceTimeoutOrCanceledError struct {
 	cause error
 }
 
 // NewWorkflowUpdateServiceTimeoutOrCanceledError creates a new WorkflowUpdateServiceTimeoutOrCanceledError.
+//
+// Exposed as: [go.temporal.io/sdk/client.NewWorkflowUpdateServiceTimeoutOrCanceledError]
 func NewWorkflowUpdateServiceTimeoutOrCanceledError(err error) *WorkflowUpdateServiceTimeoutOrCanceledError {
 	return &WorkflowUpdateServiceTimeoutOrCanceledError{
 		cause: err,

internal/cmd/build/main.go

@@ -108,6 +108,10 @@ func (b *builder) check() error {
 	if err := b.runCmd(b.cmdFromRoot("go", "run", "./internal/cmd/tools/copyright/licensegen.go", "--verifyOnly")); err != nil {
 		return fmt.Errorf("copyright check failed: %w", err)
 	}
+	// Run doclink check
+	if err := b.runCmd(b.cmdFromRoot("go", "run", "./internal/cmd/tools/doclink/doclink.go")); err != nil {
+		return fmt.Errorf("copyright check failed: %w", err)
+	}
 	return nil
 }