Add godoc for drp stucts

data_retention_policy.go

@@ -21,8 +21,12 @@ func (d DataRetentionPolicyChoice) IsPopulated() bool {
 		d.DataRetentionPolicyDontDelete != nil
 }
 
-// convert to legacy DataRetentionPolicy struct
+// Convert the DataRetentionPolicyChoice to the legacy DataRetentionPolicy struct
+// Returns nil if the policy cannot be represented by a legacy DataRetentionPolicy
 func (d *DataRetentionPolicyChoice) ConvertToLegacyStruct() *DataRetentionPolicy {
+	if d == nil {
+		return nil
+	}
 	if d.DataRetentionPolicy != nil {
 		// TFE v202311-1 and v202312-1 will return a deprecated DataRetentionPolicy in the DataRetentionPolicyChoice struct
 		return d.DataRetentionPolicy
@@ -37,13 +41,16 @@ func (d *DataRetentionPolicyChoice) ConvertToLegacyStruct() *DataRetentionPolicy
 }
 
 // DataRetentionPolicy describes the retention policy of deleting records older than the specified number of days.
+//
 // Deprecated: Use DataRetentionPolicyDeleteOlder instead. This is the original representation of a
 // data retention policy, only present in TFE v202311-1 and v202312-1
 type DataRetentionPolicy struct {
 	ID                   string `jsonapi:"primary,data-retention-policies"`
 	DeleteOlderThanNDays int    `jsonapi:"attr,delete-older-than-n-days"`
 }
 
+// DataRetentionPolicySetOptions is the options for a creating a DataRetentionPolicy.
+//
 // Deprecated: Use DataRetentionPolicyDeleteOlder variations instead
 type DataRetentionPolicySetOptions struct {
 	// Type is a public field utilized by JSON:API to
@@ -52,28 +59,36 @@ type DataRetentionPolicySetOptions struct {
 	// https://jsonapi.org/format/#crud-creating
 	Type string `jsonapi:"primary,data-retention-policies"`
 
+	// DeleteOlderThanNDays is the number of days to retain records for.
 	DeleteOlderThanNDays int `jsonapi:"attr,delete-older-than-n-days"`
 }
 
+// DataRetentionPolicyDeleteOlder describes the retention policy of deleting records older than the specified number of days.
 type DataRetentionPolicyDeleteOlder struct {
-	ID                   string `jsonapi:"primary,data-retention-policy-delete-olders"`
-	DeleteOlderThanNDays int    `jsonapi:"attr,delete-older-than-n-days"`
+	ID string `jsonapi:"primary,data-retention-policy-delete-olders"`
+
+	// DeleteOlderThanNDays is the number of days to retain records for.
+	DeleteOlderThanNDays int `jsonapi:"attr,delete-older-than-n-days"`
 }
 
+// DataRetentionPolicyDontDelete describes the retention policy of never deleting records.
 type DataRetentionPolicyDontDelete struct {
 	ID string `jsonapi:"primary,data-retention-policy-dont-deletes"`
 }
 
+// DataRetentionPolicyDeleteOlderSetOptions describes the options for a creating a DataRetentionPolicyDeleteOlder.
 type DataRetentionPolicyDeleteOlderSetOptions struct {
 	// Type is a public field utilized by JSON:API to
 	// set the resource type via the field tag.
 	// It is not a user-defined value and does not need to be set.
 	// https://jsonapi.org/format/#crud-creating
 	Type string `jsonapi:"primary,data-retention-policy-delete-olders"`
 
+	// DeleteOlderThanNDays is the number of days records will be retained for after their creation.
 	DeleteOlderThanNDays int `jsonapi:"attr,delete-older-than-n-days"`
 }
 
+// DataRetentionPolicyDontDeleteSetOptions describes the options for a creating a DataRetentionPolicyDontDelete.
 type DataRetentionPolicyDontDeleteSetOptions struct {
 	// Type is a public field utilized by JSON:API to
 	// set the resource type via the field tag.

organization.go

@@ -46,16 +46,20 @@ type Organizations interface {
 	// ReadRunQueue shows the current run queue of an organization.
 	ReadRunQueue(ctx context.Context, organization string, options ReadRunQueueOptions) (*RunQueue, error)
 
-	// Deprecated: Use ReadDataRetentionPolicyV2 instead.
+	// ReadDataRetentionPolicy reads an organization's data retention policy
 	// **Note: This functionality is only available in Terraform Enterprise versions v202311-1 and v202312-1.**
+	//
+	// Deprecated: Use ReadDataRetentionPolicyV2 instead.
 	ReadDataRetentionPolicy(ctx context.Context, organization string) (*DataRetentionPolicy, error)
 
 	// ReadDataRetentionPolicyV2 reads an organization's data retention policy
 	// **Note: This functionality is only available in Terraform Enterprise.**
 	ReadDataRetentionPolicyV2(ctx context.Context, organization string) (*DataRetentionPolicyChoice, error)
 
-	// Deprecated: Use SetDataRetentionPolicyDeleteOlder instead
+	// SetDataRetentionPolicy sets an organization's data retention policy
 	// **Note: This functionality is only available in Terraform Enterprise versions v202311-1 and v202312-1.**
+	//
+	// Deprecated: Use SetDataRetentionPolicyDeleteOlder instead
 	SetDataRetentionPolicy(ctx context.Context, organization string, options DataRetentionPolicySetOptions) (*DataRetentionPolicy, error)
 
 	// SetDataRetentionPolicyDeleteOlder sets an organization's data retention policy to delete data older than a certain number of days
@@ -353,9 +357,7 @@ func (s *organizations) ReadWithOptions(ctx context.Context, organization string
 	}
 
 	// Manually populate the deprecated DataRetentionPolicy field
-	if org.DataRetentionPolicyChoice != nil {
-		org.DataRetentionPolicy = org.DataRetentionPolicyChoice.ConvertToLegacyStruct()
-	}
+	org.DataRetentionPolicy = org.DataRetentionPolicyChoice.ConvertToLegacyStruct()
 
 	return org, nil
 }

workspace.go

@@ -104,6 +104,8 @@ type Workspaces interface {
 	// RemoveTags removes tags from a workspace
 	RemoveTags(ctx context.Context, workspaceID string, options WorkspaceRemoveTagsOptions) error
 
+	// ReadDataRetentionPolicy reads a workspace's data retention policy
+	//
 	// Deprecated: Use ReadDataRetentionPolicyV2 instead.
 	// **Note: This functionality is only available in Terraform Enterprise versions v202311-1 and v202312-1.**
 	ReadDataRetentionPolicy(ctx context.Context, workspaceID string) (*DataRetentionPolicy, error)
@@ -112,6 +114,8 @@ type Workspaces interface {
 	// **Note: This functionality is only available in Terraform Enterprise.**
 	ReadDataRetentionPolicyV2(ctx context.Context, workspaceID string) (*DataRetentionPolicyChoice, error)
 
+	// SetDataRetentionPolicy sets a workspace's data retention policy to delete data older than a certain number of days
+	//
 	// Deprecated: Use SetDataRetentionPolicyDeleteOlder instead
 	// **Note: This functionality is only available in Terraform Enterprise versions v202311-1 and v202312-1.**
 	SetDataRetentionPolicy(ctx context.Context, workspaceID string, options DataRetentionPolicySetOptions) (*DataRetentionPolicy, error)
@@ -755,9 +759,7 @@ func (s *workspaces) ReadWithOptions(ctx context.Context, organization, workspac
 	}
 
 	// Manually populate the deprecated DataRetentionPolicy field
-	if w.DataRetentionPolicyChoice != nil {
-		w.DataRetentionPolicy = w.DataRetentionPolicyChoice.ConvertToLegacyStruct()
-	}
+	w.DataRetentionPolicy = w.DataRetentionPolicyChoice.ConvertToLegacyStruct()
 
 	// durations come over in ms
 	w.ApplyDurationAverage *= time.Millisecond