doc: improve descriptions

trocco-io · Feb 27, 2025 · d983eba · d983eba
1 parent 05511c5
commit d983eba
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 30 deletions.
diff --git a/internal/provider/connection_resource.go b/internal/provider/connection_resource.go
@@ -273,7 +273,7 @@ func (r *connectionResource) Schema(
 		Attributes: map[string]schema.Attribute{
 			// Common Fields
 			"connection_type": schema.StringAttribute{
-				MarkdownDescription: "The type of the connection. It must be one of `bigquery`, `snowflake`, `gcs`, `google_spreadsheets`, `mysql`, `salesforce`, or `s3`.",
+				MarkdownDescription: "The type of the connection. It must be one of `bigquery`, `snowflake`, `gcs`, `google_spreadsheets`, `mysql`, `salesforce`, `s3`, or `postgresql`.",
 				Required:            true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
@@ -307,7 +307,7 @@ func (r *connectionResource) Schema(
 				},
 			},
 			"resource_group_id": schema.Int64Attribute{
-				MarkdownDescription: "The ID of the resource group the connection belongs to.",
+				MarkdownDescription: "The ID of the resource group that the connection belongs to.",
 				Optional:            true,
 				Validators: []validator.Int64{
 					int64validator.AtLeast(1),
@@ -333,14 +333,14 @@ func (r *connectionResource) Schema(
 
 			// Snowflake Fields
 			"host": schema.StringAttribute{
-				MarkdownDescription: "Snowflake, PostgreSQL: The host of a (Snowflake, PostgreSQL) account.",
+				MarkdownDescription: "Snowflake, PostgreSQL: The host of a Snowflake or PostgreSQL account.",
 				Optional:            true,
 				Validators: []validator.String{
 					stringvalidator.UTF8LengthAtLeast(1),
 				},
 			},
 			"user_name": schema.StringAttribute{
-				MarkdownDescription: "Snowflake, PostgreSQL: The name of a (Snowflake, PostgreSQL) user.",
+				MarkdownDescription: "Snowflake, PostgreSQL: The name of a Snowflake or PostgreSQL user.",
 				Optional:            true,
 				Validators: []validator.String{
 					stringvalidator.UTF8LengthAtLeast(1),
@@ -361,7 +361,7 @@ func (r *connectionResource) Schema(
 				},
 			},
 			"password": schema.StringAttribute{
-				MarkdownDescription: "Snowflake, PostgreSQL: The password for the (Snowflake, PostgreSQL) user.",
+				MarkdownDescription: "Snowflake, PostgreSQL: The password for the Snowflake or PostgreSQL user.",
 				Optional:            true,
 				Sensitive:           true,
 				Validators: []validator.String{
@@ -396,7 +396,7 @@ func (r *connectionResource) Schema(
 
 			// MySQL Fields
 			"port": schema.Int64Attribute{
-				MarkdownDescription: "MySQL, PostgreSQL: The port of the (MySQL, PostgreSQL) server.",
+				MarkdownDescription: "MySQL, PostgreSQL: The port of the MySQL or PostgreSQL server.",
 				Optional:            true,
 				Validators: []validator.Int64{
 					int64validator.AtLeast(1),
@@ -409,7 +409,7 @@ func (r *connectionResource) Schema(
 				Optional:            true,
 				Attributes: map[string]schema.Attribute{
 					"ca": schema.StringAttribute{
-						MarkdownDescription: "MySQL, PostgreSQL: CA certificate",
+						MarkdownDescription: "MySQL, PostgreSQL: CA certificate.",
 						Optional:            true,
 						Sensitive:           true,
 						Validators: []validator.String{
@@ -419,7 +419,7 @@ func (r *connectionResource) Schema(
 						Default:  stringdefault.StaticString(""),
 					},
 					"cert": schema.StringAttribute{
-						MarkdownDescription: "MySQL, PostgreSQL: Certificate (CRT file)",
+						MarkdownDescription: "MySQL, PostgreSQL: Certificate (CRT file).",
 						Optional:            true,
 						Sensitive:           true,
 						Validators: []validator.String{
@@ -429,7 +429,7 @@ func (r *connectionResource) Schema(
 						Default:  stringdefault.StaticString(""),
 					},
 					"key": schema.StringAttribute{
-						MarkdownDescription: "MySQL, PostgreSQL: Key (KEY file)",
+						MarkdownDescription: "MySQL, PostgreSQL: Key (KEY file).",
 						Optional:            true,
 						Sensitive:           true,
 						Validators: []validator.String{
@@ -448,19 +448,19 @@ func (r *connectionResource) Schema(
 				},
 			},
 			"gateway": schema.SingleNestedAttribute{
-				MarkdownDescription: "MySQL, PostgreSQL: Whether to connect via SSH",
+				MarkdownDescription: "MySQL, PostgreSQL: Whether to connect via SSH.",
 				Optional:            true,
 				Attributes: map[string]schema.Attribute{
 					"host": schema.StringAttribute{
-						MarkdownDescription: "MySQL, PostgreSQL: SSH Host",
+						MarkdownDescription: "MySQL, PostgreSQL: SSH Host.",
 						Optional:            true,
 						Sensitive:           true,
 						Validators: []validator.String{
 							stringvalidator.UTF8LengthAtLeast(1),
 						},
 					},
 					"port": schema.Int64Attribute{
-						MarkdownDescription: "MySQL, PostgreSQL: SSH Port",
+						MarkdownDescription: "MySQL, PostgreSQL: SSH Port.",
 						Optional:            true,
 						Sensitive:           true,
 						Validators: []validator.Int64{
@@ -469,29 +469,29 @@ func (r *connectionResource) Schema(
 						},
 					},
 					"user_name": schema.StringAttribute{
-						MarkdownDescription: "MySQL, PostgreSQL: SSH User",
+						MarkdownDescription: "MySQL, PostgreSQL: SSH User.",
 						Optional:            true,
 						Sensitive:           true,
 						Validators: []validator.String{
 							stringvalidator.UTF8LengthAtLeast(1),
 						},
 					},
 					"password": schema.StringAttribute{
-						MarkdownDescription: "MySQL, PostgreSQL: SSH Password",
+						MarkdownDescription: "MySQL, PostgreSQL: SSH Password.",
 						Optional:            true,
 						Computed:            true,
 						Sensitive:           true,
 						Default:             stringdefault.StaticString(""),
 					},
 					"key": schema.StringAttribute{
-						MarkdownDescription: "MySQL, PostgreSQL: SSH Private Key",
+						MarkdownDescription: "MySQL, PostgreSQL: SSH Private Key.",
 						Optional:            true,
 						Computed:            true,
 						Sensitive:           true,
 						Default:             stringdefault.StaticString(""),
 					},
 					"key_passphrase": schema.StringAttribute{
-						MarkdownDescription: "MySQL, PostgreSQL: SSH Private Key Passphrase",
+						MarkdownDescription: "MySQL, PostgreSQL: SSH Private Key Passphrase.",
 						Optional:            true,
 						Computed:            true,
 						Sensitive:           true,

diff --git a/internal/provider/job_definition_resource.go b/internal/provider/job_definition_resource.go
@@ -86,40 +86,40 @@ func (r *jobDefinitionResource) Configure(
 
 func (r *jobDefinitionResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "Provides a TROCCO job definitions.",
+		MarkdownDescription: "Provides a TROCCO job definition.",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.Int64Attribute{
 				Computed: true,
 				PlanModifiers: []planmodifier.Int64{
 					int64planmodifier.UseStateForUnknown(),
 				},
-				MarkdownDescription: "The ID of the job definition",
+				MarkdownDescription: "The ID of the job definition.",
 			},
 			"name": schema.StringAttribute{
 				Required: true,
 				Validators: []validator.String{
 					stringvalidator.UTF8LengthAtMost(255),
 				},
-				MarkdownDescription: "Name of the job definition. It must be less than 256 characters",
+				MarkdownDescription: "The name of the job definition. It must be less than 256 characters.",
 			},
 			"description": schema.StringAttribute{
 				Optional:            true,
-				MarkdownDescription: "Description of the job definition.",
+				MarkdownDescription: "The description of the job definition.",
 			},
 			"resource_group_id": schema.Int64Attribute{
 				Optional: true,
 				Validators: []validator.Int64{
 					int64validator.AtLeast(1),
 				},
-				MarkdownDescription: "ID of the resource group to which the job definition belongs",
+				MarkdownDescription: "The ID of the resource group to which the job definition belongs.",
 			},
 			"resource_enhancement": schema.StringAttribute{
 				Optional: true,
 				Computed: true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
-				MarkdownDescription: "Resource size to be used when executing the job. If not specified, the resource size specified in the transfer settings is applied. The value that can be specified varies depending on the connector. (This parameter is available only in the Professional plan.",
+				MarkdownDescription: "The resource size to be used when executing the job. If not specified, the resource size specified in the transfer settings is applied. The value that can be specified varies depending on the connector. This parameter is available only in the Professional plan.",
 				Validators: []validator.String{
 					stringvalidator.OneOf("medium", "custom_spec", "large", "xlarge"),
 				},
@@ -128,7 +128,7 @@ func (r *jobDefinitionResource) Schema(ctx context.Context, req resource.SchemaR
 				Optional:            true,
 				Computed:            true,
 				Default:             booldefault.StaticBool(false),
-				MarkdownDescription: "Specifies whether or not to run a job if another job with the same job definition is running at the time the job is run",
+				MarkdownDescription: "Specifies whether to run a job if another job with the same job definition is running at the time the job is run.",
 			},
 			"retry_limit": schema.Int64Attribute{
 				Optional: true,
@@ -137,7 +137,7 @@ func (r *jobDefinitionResource) Schema(ctx context.Context, req resource.SchemaR
 				Validators: []validator.Int64{
 					int64validator.Between(0, 10),
 				},
-				MarkdownDescription: "Maximum number of retries. if set 0, the job will not be retried",
+				MarkdownDescription: "The maximum number of retries. If set to 0, the job will not be retried.",
 			},
 			"input_option_type": schema.StringAttribute{
 				Required: true,
@@ -147,7 +147,7 @@ func (r *jobDefinitionResource) Schema(ctx context.Context, req resource.SchemaR
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},
-				MarkdownDescription: "Input option type.",
+				MarkdownDescription: "The input option type.",
 			},
 			"input_option": job_definition.InputOptionSchema(),
 			"output_option_type": schema.StringAttribute{
@@ -158,7 +158,7 @@ func (r *jobDefinitionResource) Schema(ctx context.Context, req resource.SchemaR
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},
-				MarkdownDescription: "Output option type.",
+				MarkdownDescription: "The output option type.",
 			},
 			"output_option":               job_definition.OutputOptionSchema(),
 			"filter_columns":              filters.FilterColumnsSchema(),

diff --git a/internal/provider/resource_group_resource.go b/internal/provider/resource_group_resource.go
@@ -56,7 +56,7 @@ func (r *resourceGroupResource) Configure(ctx context.Context, req resource.Conf
 
 func (r *resourceGroupResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "Provides a TROCCO resource_group resource.",
+		MarkdownDescription: "Provides a TROCCO resource group resource.",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.Int64Attribute{
 				Computed: true,
@@ -96,7 +96,7 @@ func (r *resourceGroupResource) Schema(ctx context.Context, req resource.SchemaR
 							Validators: []validator.String{
 								stringvalidator.OneOf("administrator", "editor", "operator", "viewer"),
 							},
-							MarkdownDescription: "The role of the team. Valid values are `administrator`, `editor`, `operator`, `viewer`.",
+							MarkdownDescription: "The role of the team. Valid values are `administrator`, `editor`, `operator`, and `viewer`.",
 						},
 					},
 				},

diff --git a/internal/provider/user_resource.go b/internal/provider/user_resource.go
@@ -104,14 +104,14 @@ func (r *userResource) Schema(ctx context.Context, req resource.SchemaRequest, r
 						stringvalidator.RegexMatches(regexp.MustCompile(`[0-9]`), "must contain at least one number"),
 					),
 				},
-				MarkdownDescription: "The password of the user. It must be at least 8 characters long and contain at least one letter and one number. It is required when creating a new user but optional during updates.",
+				MarkdownDescription: "The password of the user. It must be at least 8 characters long and contain at least one letter and one number. It is required when creating a new user but is optional during updates.",
 			},
 			"role": schema.StringAttribute{
 				Required: true,
 				Validators: []validator.String{
 					stringvalidator.OneOf("super_admin", "admin", "member"),
 				},
-				MarkdownDescription: "The role of the user. Valid value is `super_admin`, `admin`, or `member`.",
+				MarkdownDescription: "The role of the user. Valid values are `super_admin`, `admin`, and `member`.",
 			},
 			"can_use_audit_log": schema.BoolAttribute{
 				Optional: true,