Add missing documentation for exposed structs in internal package

Author: brucearctor

internal/activity.go

@@ -18,14 +18,17 @@ type (
 	//
 	// Exposed as: [go.temporal.io/sdk/activity.Type]
 	ActivityType struct {
+		// Name is the name of the activity type.
 		Name string
 	}
 
 	// ActivityInfo contains information about a currently executing activity.
 	//
 	// Exposed as: [go.temporal.io/sdk/activity.Info]
 	ActivityInfo struct {
+		// TaskToken is the token that identifies the activity task.
 		TaskToken    []byte
+		// WorkflowType is the type of the workflow that started this activity.
 		WorkflowType *WorkflowType
 		// Namespace of the workflow that started this activity. Empty if this activity was not started by a workflow.
 		// If present, the value is always the same as Namespace since workflows can only run activities in their own
@@ -36,9 +39,13 @@ type (
 		// Execution details of the workflow that started this activity. All fields are empty if this activity was not
 		// started by a workflow.
 		WorkflowExecution      WorkflowExecution
+		// ActivityID is the ID of the activity.
 		ActivityID             string
+		// ActivityRunID is the run ID of the activity. Empty if the activity was started by a workflow.
 		ActivityRunID          string // Run ID of the activity. Empty if the activity was started by a workflow.
+		// ActivityType is the type of the activity.
 		ActivityType           ActivityType
+		// TaskQueue is the name of the task queue that the activity needs to be scheduled on.
 		TaskQueue              string
 		Namespace              string        // Namespace of this activity.
 		HeartbeatTimeout       time.Duration // Maximum time between heartbeats. 0 means no heartbeat needed.
@@ -73,6 +80,7 @@ type (
 		// ambiguity between string names and function references. Also users should
 		// always use this string name when executing this activity.
 		Name                          string
+		// DisableAlreadyRegisteredCheck disables the check for already registered activities.
 		DisableAlreadyRegisteredCheck bool
 
 		// When registering a struct with activities, skip functions that are not valid activities. If false,

internal/cmd/tools/doclink/doclink.go

@@ -127,6 +127,11 @@ func run() error {
 			if err != nil {
 				return fmt.Errorf("error while parsing internal files: %v", err)
 			}
+
+			err = checkInternalDocs(path, file, publicToInternal)
+			if err != nil {
+				return fmt.Errorf("error while checking internal docs: %v", err)
+			}
 		}
 		return nil
 	})
@@ -587,3 +592,84 @@ func isValidDefinitionWithMatch(line, private string, inGroup string, insideStru
 	}
 	return false
 }
+
+func checkInternalDocs(path string, file *os.File, pairs map[string]map[string]string) error {
+	fs := token.NewFileSet()
+
+	// Reset file pointer to start
+	_, err := file.Seek(0, 0)
+	if err != nil {
+		return fmt.Errorf("failed to seek: %v", err)
+	}
+
+	node, err := parser.ParseFile(fs, path, file, parser.ParseComments)
+	if err != nil {
+		return fmt.Errorf("failed to parse file %s: %v", path, err)
+	}
+
+	exposedTypes := make(map[string]bool)
+	for _, pair := range pairs {
+		for _, private := range pair {
+			exposedTypes[private] = true
+		}
+	}
+
+	ast.Inspect(node, func(n ast.Node) bool {
+		if genDecl, ok := n.(*ast.GenDecl); ok && genDecl.Tok == token.TYPE {
+			for _, spec := range genDecl.Specs {
+				if typeSpec, ok := spec.(*ast.TypeSpec); ok {
+					if !exposedTypes[typeSpec.Name.Name] {
+						continue
+					}
+					if structType, ok := typeSpec.Type.(*ast.StructType); ok {
+						for _, field := range structType.Fields.List {
+							isExported := false
+							var fieldName string
+							if len(field.Names) > 0 {
+								for _, name := range field.Names {
+									if ast.IsExported(name.Name) {
+										isExported = true
+										fieldName = name.Name
+										break
+									}
+								}
+							} else {
+								// Check anonymous field
+								if ident, ok := field.Type.(*ast.Ident); ok {
+									if ast.IsExported(ident.Name) {
+										isExported = true
+										fieldName = ident.Name
+									}
+								} else if sel, ok := field.Type.(*ast.SelectorExpr); ok {
+									if ast.IsExported(sel.Sel.Name) {
+										isExported = true
+										fieldName = sel.Sel.Name
+									}
+								} else if star, ok := field.Type.(*ast.StarExpr); ok {
+									if ident, ok := star.X.(*ast.Ident); ok {
+										if ast.IsExported(ident.Name) {
+											isExported = true
+											fieldName = ident.Name
+										}
+									} else if sel, ok := star.X.(*ast.SelectorExpr); ok {
+										if ast.IsExported(sel.Sel.Name) {
+											isExported = true
+											fieldName = sel.Sel.Name
+										}
+									}
+								}
+							}
+
+							if isExported && field.Doc == nil && field.Comment == nil {
+								changesNeeded = true
+								fmt.Printf("Missing doc for exposed struct %s field %s in %s\n", typeSpec.Name.Name, fieldName, path)
+							}
+						}
+					}
+				}
+			}
+		}
+		return true
+	})
+	return nil
+}

internal/error.go

@@ -193,11 +193,17 @@ type (
 	// Exposed as: [go.temporal.io/sdk/workflow.ContinueAsNewError]
 	ContinueAsNewError struct {
 		// params *ExecuteWorkflowParams
+		// WorkflowType is the type of the workflow.
 		WorkflowType        *WorkflowType
+		// Input is the payload of the workflow.
 		Input               *commonpb.Payloads
+		// Header is the header of the workflow.
 		Header              *commonpb.Header
+		// TaskQueueName is the task queue that the workflow is running on.
 		TaskQueueName       string
+		// WorkflowRunTimeout is the timeout for a single run of the workflow execution.
 		WorkflowRunTimeout  time.Duration
+		// WorkflowTaskTimeout is the maximum execution time of a single Workflow Task.
 		WorkflowTaskTimeout time.Duration
 
 		// Deprecated: WorkflowExecutionTimeout is deprecated and is never set or