fix: improve coder_script related docs

Author: mafredri

provider/agent.go

@@ -17,7 +17,7 @@ import (
 func agentResource() *schema.Resource {
 	return &schema.Resource{
 		Description: "Use this resource to associate an agent.",
-		CreateContext: func(ctx context.Context, resourceData *schema.ResourceData, i interface{}) diag.Diagnostics {
+		CreateContext: func(_ context.Context, resourceData *schema.ResourceData, i interface{}) diag.Diagnostics {
 			// This should be a real authentication token!
 			resourceData.SetId(uuid.NewString())
 			err := resourceData.Set("token", uuid.NewString())
@@ -121,7 +121,7 @@ func agentResource() *schema.Resource {
 			},
 			"startup_script": {
 				ForceNew:    true,
-				Description: "A script to run after the agent starts. The script should exit when it is done to signal that the agent is ready.",
+				Description: `A script to run after the agent starts. The script should exit when it is done to signal that the agent is ready. This option is an alias for defining a "coder_script" resource with "run_on_start" set to true.`,
 				Type:        schema.TypeString,
 				Optional:    true,
 			},
@@ -138,7 +138,7 @@ func agentResource() *schema.Resource {
 				Type:        schema.TypeString,
 				ForceNew:    true,
 				Optional:    true,
-				Description: "A script to run before the agent is stopped. The script should exit when it is done to signal that the workspace can be stopped.",
+				Description: `A script to run before the agent is stopped. The script should exit when it is done to signal that the workspace can be stopped. This option is an alias for defining a "coder_script" resource with "run_on_stop" set to true.`,
 			},
 			"shutdown_script_timeout": {
 				Type:         schema.TypeInt,
@@ -197,7 +197,7 @@ func agentResource() *schema.Resource {
 				Type:          schema.TypeString,
 				ForceNew:      true,
 				Optional:      true,
-				Description:   "This option sets the behavior of the `startup_script`. When set to \"blocking\", the startup_script must exit before the workspace is ready. When set to \"non-blocking\", the startup_script may run in the background and the workspace will be ready immediately. Default is \"non-blocking\", although \"blocking\" is recommended.",
+				Description:   `This option sets the behavior of the "startup_script". When set to "blocking", the startup_script must exit before the workspace is ready. When set to "non-blocking", the startup_script may run in the background and the workspace will be ready immediately. Default is "non-blocking", although "blocking" is recommended. This option is an alias for defining a "coder_script" resource with "start_blocks_login" set to true (blocking).`,
 				ValidateFunc:  validation.StringInSlice([]string{"blocking", "non-blocking"}, false),
 				ConflictsWith: []string{"login_before_ready"},
 			},

provider/script.go

@@ -16,7 +16,7 @@ var ScriptCRONParser = cron.NewParser(cron.Second | cron.Minute | cron.Hour | cr
 func scriptResource() *schema.Resource {
 	return &schema.Resource{
 		Description: "Use this resource to run a script from an agent.",
-		CreateContext: func(ctx context.Context, rd *schema.ResourceData, i interface{}) diag.Diagnostics {
+		CreateContext: func(_ context.Context, rd *schema.ResourceData, _ interface{}) diag.Diagnostics {
 			rd.SetId(uuid.NewString())
 			runOnStart, _ := rd.Get("run_on_start").(bool)
 			runOnStop, _ := rd.Get("run_on_stop").(bool)
@@ -60,14 +60,14 @@ func scriptResource() *schema.Resource {
 				ForceNew:    true,
 				Type:        schema.TypeString,
 				Required:    true,
-				Description: "The script to run.",
+				Description: "The content of the script that will be run.",
 			},
 			"cron": {
 				ForceNew:    true,
 				Type:        schema.TypeString,
 				Optional:    true,
 				Description: "The cron schedule to run the script on. This is a cron expression.",
-				ValidateFunc: func(i interface{}, s string) ([]string, []error) {
+				ValidateFunc: func(i interface{}, _ string) ([]string, []error) {
 					v, ok := i.(string)
 					if !ok {
 						return []string{}, []error{fmt.Errorf("got type %T instead of string", i)}
@@ -84,28 +84,28 @@ func scriptResource() *schema.Resource {
 				Default:     false,
 				ForceNew:    true,
 				Optional:    true,
-				Description: "This option defines whether or not the user can (by default) login to the workspace before this script completes running on start. When enabled, users may see an incomplete workspace when logging in.",
+				Description: "This option determines whether users can log in immediately or must wait for the workspace to finish running this script upon startup. If not enabled, users may encounter an incomplete workspace when logging in. This option only sets the default, the user can still manually override the behavior.",
 			},
 			"run_on_start": {
 				Type:        schema.TypeBool,
 				Default:     false,
 				ForceNew:    true,
 				Optional:    true,
-				Description: "This option defines whether or not the script should run when the agent starts.",
+				Description: "This option defines whether or not the script should run when the agent starts. The script should exit when it is done to signal that the agent is ready.",
 			},
 			"run_on_stop": {
 				Type:        schema.TypeBool,
 				Default:     false,
 				ForceNew:    true,
 				Optional:    true,
-				Description: "This option defines whether or not the script should run when the agent stops.",
+				Description: "This option defines whether or not the script should run when the agent stops. The script should exit when it is done to signal that the workspace can be stopped.",
 			},
 			"timeout": {
 				Type:         schema.TypeInt,
 				Default:      0,
 				ForceNew:     true,
 				Optional:     true,
-				Description:  "Time in seconds until the agent lifecycle status is marked as timed out, this happens when the script has not completed (exited) in the given time.",
+				Description:  "Time in seconds that the script is allowed to run. If the script does not complete within this time, the script is terminated and the agent lifecycle status is marked as timed out. A value of zero (default) means no timeout.",
 				ValidateFunc: validation.IntAtLeast(1),
 			},
 		},