feat(userconfig/desc): add entity and availability types

docs/resources/organization_application_user.md

@@ -3,17 +3,18 @@
 page_title: "aiven_organization_application_user Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  Creates and manages an organization application user. Application users can be used for programmatic access to the platform. This features is in the limited availability stage. Contact [email protected] to try this feature.
-  This resource is in beta and may change without notice. To use this resource,
-  set the PROVIDER_AIVEN_ENABLE_BETA environment variable to true.
+  Creates and manages an organization application user. Application users can be used for programmatic access to the platform.
+  This resource is in the limited availability stage and may change without notice.
+  To enable this feature, contact the sales team mailto:[email protected]. After it's enabled, set
+  the PROVIDER_AIVEN_ENABLE_BETA environment variable to use the resource.
 ---
 
 # aiven_organization_application_user (Resource)
 
-Creates and manages an organization application user. Application users can be used for programmatic access to the platform. This features is in the limited availability stage. Contact [email protected] to try this feature.
-
-**This resource is in beta and may change without notice.** To use this resource, 
-set the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to true.
+Creates and manages an organization application user. Application users can be used for programmatic access to the platform. 
+**This resource is in the limited availability stage and may change without notice.** 
+To enable this feature, contact the [sales team](mailto:[email protected]). After it's enabled, set
+the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource.
 
 
 

docs/resources/organization_application_user_token.md

@@ -4,16 +4,15 @@ page_title: "aiven_organization_application_user_token Resource - terraform-prov
 subcategory: ""
 description: |-
   Creates and manages an organization application user token in Aiven.
-  This resource is in beta and may change without notice. To use this resource,
-  set the PROVIDER_AIVEN_ENABLE_BETA environment variable to true.
+  This resource is in the beta stage and may change without notice. Set
+  the PROVIDER_AIVEN_ENABLE_BETA environment variable to use the resource.
 ---
 
 # aiven_organization_application_user_token (Resource)
 
-Creates and manages an organization application user token in Aiven.
-
-**This resource is in beta and may change without notice.** To use this resource, 
-set the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to true.
+Creates and manages an organization application user token in Aiven. 
+**This resource is in the beta stage and may change without notice.** Set
+the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource.
 
 
 

docs/resources/organization_group_project.md

@@ -3,19 +3,16 @@
 page_title: "aiven_organization_group_project Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  Adds and manages a group https://aiven.io/docs/platform/concepts/projects_accounts_access#groups
-              of users as members of a project https://aiven.io/docs/platform/reference/project-member-privileges.
-  This resource is in beta and may change without notice. To use this resource,
-  set the PROVIDER_AIVEN_ENABLE_BETA environment variable to true.
+  Adds and manages a group https://aiven.io/docs/platform/concepts/projects_accounts_access#groups of users as members of a project https://aiven.io/docs/platform/reference/project-member-privileges.
+  This resource is in the beta stage and may change without notice. Set
+  the PROVIDER_AIVEN_ENABLE_BETA environment variable to use the resource.
 ---
 
 # aiven_organization_group_project (Resource)
 
-Adds and manages a [group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups) 
-			of users as [members of a project](https://aiven.io/docs/platform/reference/project-member-privileges).
-
-**This resource is in beta and may change without notice.** To use this resource, 
-set the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to true.
+Adds and manages a [group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups) of users as [members of a project](https://aiven.io/docs/platform/reference/project-member-privileges). 
+**This resource is in the beta stage and may change without notice.** Set
+the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource.
 
 ## Example Usage
 

docs/resources/organization_user_group_member.md

@@ -4,16 +4,15 @@ page_title: "aiven_organization_user_group_member Resource - terraform-provider-
 subcategory: ""
 description: |-
   Adds and manages users in a user group https://aiven.io/docs/platform/concepts/projects_accounts_access#groups.
-  This resource is in beta and may change without notice. To use this resource,
-  set the PROVIDER_AIVEN_ENABLE_BETA environment variable to true.
+  This resource is in the beta stage and may change without notice. Set
+  the PROVIDER_AIVEN_ENABLE_BETA environment variable to use the resource.
 ---
 
 # aiven_organization_user_group_member (Resource)
 
-Adds and manages users in a [user group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups).
-
-**This resource is in beta and may change without notice.** To use this resource, 
-set the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to true.
+Adds and manages users in a [user group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups). 
+**This resource is in the beta stage and may change without notice.** Set
+the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource.
 
 ## Example Usage
 

internal/plugin/service/organization/organization_application_user.go

@@ -15,6 +15,7 @@ import (
 
 	"github.com/aiven/terraform-provider-aiven/internal/plugin/errmsg"
 	"github.com/aiven/terraform-provider-aiven/internal/plugin/util"
+	"github.com/aiven/terraform-provider-aiven/internal/schemautil/userconfig"
 )
 
 var (
@@ -78,7 +79,13 @@ func (r *organizationApplicationUser) Schema(
 	resp *resource.SchemaResponse,
 ) {
 	resp.Schema = util.GeneralizeSchema(ctx, schema.Schema{
-		Description: util.BetaDescription("Creates and manages an organization application user. Application users can be used for programmatic access to the platform. This features is in the limited availability stage. Contact [email protected] to try this feature."),
+		Description: userconfig.
+			Desc(
+				"Creates and manages an organization application user. Application users can be used for " +
+					"programmatic access to the platform.",
+			).
+			AvailabilityType(userconfig.Limited).
+			Build(),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				Description: "Compound identifier of the organization application user.",

internal/plugin/service/organization/organization_application_user_token.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/aiven/terraform-provider-aiven/internal/plugin/errmsg"
 	"github.com/aiven/terraform-provider-aiven/internal/plugin/util"
+	"github.com/aiven/terraform-provider-aiven/internal/schemautil/userconfig"
 )
 
 var (
@@ -108,7 +109,9 @@ func (r *organizationApplicationUserToken) Schema(
 	resp *resource.SchemaResponse,
 ) {
 	resp.Schema = util.GeneralizeSchema(ctx, schema.Schema{
-		Description: util.BetaDescription("Creates and manages an organization application user token in Aiven."),
+		Description: userconfig.Desc("Creates and manages an organization application user token in Aiven.").
+			AvailabilityType(userconfig.Beta).
+			Build(),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				Description: "Compound identifier of the organization application user token.",

internal/plugin/service/organization/organization_group_project.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/aiven/terraform-provider-aiven/internal/plugin/errmsg"
 	"github.com/aiven/terraform-provider-aiven/internal/plugin/util"
+	"github.com/aiven/terraform-provider-aiven/internal/schemautil/userconfig"
 )
 
 var (
@@ -77,10 +78,13 @@ func (r *organizationGroupProjectResource) Schema(
 	_ resource.SchemaRequest,
 	resp *resource.SchemaResponse) {
 	resp.Schema = util.GeneralizeSchema(ctx, schema.Schema{
-		Description: util.BetaDescription(
-			`Adds and manages a [group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups) 
-			of users as [members of a project](https://aiven.io/docs/platform/reference/project-member-privileges).`,
-		),
+		Description: userconfig.Desc(
+			"Adds and manages a " +
+				"[group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups) of users as " +
+				"[members of a project](https://aiven.io/docs/platform/reference/project-member-privileges).",
+		).
+			AvailabilityType(userconfig.Beta).
+			Build(),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				Description: "A compound identifier of the resource in the format `project/group_id`.",

internal/plugin/service/organization/organization_user_group_member.go

@@ -15,6 +15,7 @@ import (
 
 	"github.com/aiven/terraform-provider-aiven/internal/plugin/errmsg"
 	"github.com/aiven/terraform-provider-aiven/internal/plugin/util"
+	"github.com/aiven/terraform-provider-aiven/internal/schemautil/userconfig"
 )
 
 var (
@@ -76,7 +77,12 @@ func (r *organizationUserGroupMembersResource) Schema(
 	resp *resource.SchemaResponse,
 ) {
 	resp.Schema = util.GeneralizeSchema(ctx, schema.Schema{
-		Description: util.BetaDescription("Adds and manages users in a [user group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups)."),
+		Description: userconfig.Desc(
+			"Adds and manages users in a " +
+				"[user group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups).",
+		).
+			AvailabilityType(userconfig.Beta).
+			Build(),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				Description: "A compound identifier of the group member in the format `organization_id/group_id/user_id`.",

internal/schemautil/userconfig/desc.go

@@ -5,23 +5,77 @@ import (
 	"strings"
 )
 
+// EntityType is a type that represents the type of an entity.
+type EntityType int
+
+const (
+	// Resource is a constant that represents the resource entity type.
+	Resource EntityType = iota
+	// DataSource is a constant that represents the data source entity type.
+	DataSource
+)
+
+// String is a function that returns the string representation of the entity type.
+func (et EntityType) String() string {
+	return [...]string{"resource", "data source"}[et]
+}
+
+// AvailabilityType is a type that represents the availability type of an entity.
+type AvailabilityType int
+
+const (
+	// Beta is a constant that represents the beta availability type.
+	Beta AvailabilityType = iota + 1
+	// Limited is a constant that represents the limited availability type.
+	Limited
+)
+
 // DescriptionBuilder is a helper to build complex descriptions in a consistent way.
 type DescriptionBuilder struct {
-	base                                string
+	// entityType is the type of the entity that the description is for.
+	entityType EntityType
+	// base is the base of the description.
+	base string
+	// availabilityType is the availability type of the entity that the description is for.
+	availabilityType AvailabilityType
+	// withForcedFirstLetterCapitalization is a flag that indicates if the first letter should be capitalized.
 	withForcedFirstLetterCapitalization bool
-	withPossibleValues                  []any
-	withRequiredWith                    []string
-	withMaxLen                          int
-	withDefaultValue                    any
-	withUseReference                    bool
-	withForceNew                        bool
+	// withPossibleValues is a flag that indicates if the possible values should be included.
+	withPossibleValues []any
+	// withRequiredWith is a flag that indicates if the required with should be included.
+	withRequiredWith []string
+	// withMaxLen is a flag that indicates if the maximum length should be included.
+	withMaxLen int
+	// withDefaultValue is a flag that indicates if the default value should be included.
+	withDefaultValue any
+	// withUseReference is a flag that indicates if the reference should be used.
+	withUseReference bool
+	// withForceNew is a flag that indicates if the force new should be included.
+	withForceNew bool
 }
 
 // Desc is a function that creates a new DescriptionBuilder.
 func Desc(base string) *DescriptionBuilder {
 	return &DescriptionBuilder{base: base}
 }
 
+// MarkAsDataSource is a function that marks the entity whose description is being built as a data source.
+//
+// All entities are considered resources by default, so this function is only needed when the entity is a data source.
+//
+// If you want to mark the entity as a resource, you don't need to call any additional functions, and you can proceed
+// further with the description building.
+func (db *DescriptionBuilder) MarkAsDataSource() *DescriptionBuilder {
+	db.entityType = DataSource
+	return db
+}
+
+// AvailabilityType is a function that sets the availabilityType field.
+func (db *DescriptionBuilder) AvailabilityType(t AvailabilityType) *DescriptionBuilder {
+	db.availabilityType = t
+	return db
+}
+
 // ForceFirstLetterCapitalization is a function that sets the withForcedFirstLetterCapitalization flag.
 func (db *DescriptionBuilder) ForceFirstLetterCapitalization() *DescriptionBuilder {
 	db.withForcedFirstLetterCapitalization = true
@@ -81,6 +135,31 @@ func (db *DescriptionBuilder) Build() string {
 		builder.WriteString(".")
 	}
 
+	if db.availabilityType != 0 {
+		builder.WriteRune(' ')
+
+		const availabilityCommonPart = `
+**This %[1]s is in the %[2]s stage and may change without notice.** %[3]s
+the ` + "`PROVIDER_AIVEN_ENABLE_BETA`" + ` environment variable to use the %[1]s.`
+
+		switch db.availabilityType {
+		case Beta:
+			builder.WriteString(fmt.Sprintf(
+				availabilityCommonPart,
+				db.entityType.String(),
+				"beta",
+				"Set",
+			))
+		case Limited:
+			builder.WriteString(fmt.Sprintf(
+				availabilityCommonPart,
+				db.entityType.String(),
+				"limited availability",
+				"\nTo enable this feature, contact the [sales team](mailto:[email protected]). After it's enabled, set",
+			))
+		}
+	}
+
 	if db.withPossibleValues != nil {
 		builder.WriteRune(' ')
 		builder.WriteString("The possible values are ")
@@ -130,7 +209,9 @@ func (db *DescriptionBuilder) Build() string {
 
 	if db.withForceNew {
 		builder.WriteRune(' ')
-		builder.WriteString("Changing this property forces recreation of the resource.")
+		builder.WriteString(fmt.Sprintf(
+			"Changing this property forces recreation of the %s.", db.entityType.String(),
+		))
 	}
 
 	return builder.String()

internal/sdkprovider/service/organization/organization_user_data_source.go

@@ -18,9 +18,12 @@ func DatasourceOrganizationUser() *schema.Resource {
 			" Organization User.",
 		Schema: map[string]*schema.Schema{
 			"organization_id": {
-				Type:        schema.TypeString,
-				Required:    true,
-				Description: userconfig.Desc("The unique organization ID").Build(),
+				Type:     schema.TypeString,
+				Required: true,
+				Description: userconfig.
+					Desc("The unique organization ID").
+					MarkAsDataSource().
+					Build(),
 			},
 			"user_id": {
 				Type:        schema.TypeString,