chore: add comments into the Options fields

options.go

@@ -13,44 +13,127 @@ type LoggerFunc func(level codersdk.LogLevel, format string, args ...interface{}
 
 // Options contains the configuration for the envbuilder.
 type Options struct {
-	SetupScript          string
-	InitScript           string
-	InitCommand          string
-	InitArgs             string
-	CacheRepo            string
-	BaseImageCacheDir    string
-	LayerCacheDir        string
-	DevcontainerDir      string
+	// SetupScript is the script to run before the init script. It runs as the
+	// root user regardless of the user specified in the devcontainer.json file.
+	// SetupScript is ran as the root user prior to the init script. It is used to
+	// configure envbuilder dynamically during the runtime. e.g. specifying
+	// whether to start systemd or tiny init for PID 1.
+	SetupScript string
+	// InitScript is the script to run to initialize the workspace.
+	InitScript string
+	// InitCommand is the command to run to initialize the workspace.
+	InitCommand string
+	// InitArgs are the arguments to pass to the init command. They are split
+	// according to /bin/sh rules with https://github.com/kballard/go-shellquote.
+	InitArgs string
+	// CacheRepo is the name of the container registry to push the cache image to.
+	// If this is empty, the cache will not be pushed.
+	CacheRepo string
+	// BaseImageCacheDir is the path to a directory where the base image can be
+	// found. This should be a read-only directory solely mounted for the purpose
+	// of caching the base image.
+	BaseImageCacheDir string
+	// LayerCacheDir is the path to a directory where built layers will be stored.
+	// This spawns an in-memory registry to serve the layers from.
+	LayerCacheDir string
+	// DevcontainerDir is the path to the folder containing the devcontainer.json
+	// file that will be used to build the workspace and can either be an absolute
+	// path or a path relative to the workspace folder. If not provided, defaults
+	// to `.devcontainer`.
+	DevcontainerDir string
+	// DevcontainerJSONPath is a path to a devcontainer.json file
+	// that is either an absolute path or a path relative to
+	// DevcontainerDir. This can be used in cases where one wants
+	// to substitute an edited devcontainer.json file for the one
+	// that exists in the repo.
+	// If neither `DevcontainerDir` nor `DevcontainerJSONPath` is provided,
+	// envbuilder will browse following directories to locate it:
+	// 1. `.devcontainer/devcontainer.json`
+	// 2. `.devcontainer.json`
+	// 3. `.devcontainer/<folder>/devcontainer.json`
 	DevcontainerJSONPath string
-	DockerfilePath       string
-	BuildContextPath     string
-	CacheTTLDays         int64
-	DockerConfigBase64   string
-	FallbackImage        string
-	ExitOnBuildFailure   bool
-	ForceSafe            bool
-	Insecure             bool
-	IgnorePaths          []string
-	SkipRebuild          bool
-	GitURL               string
-	GitCloneDepth        int64
+	// DockerfilePath is the relative path to the Dockerfile that will be used to
+	// build the workspace. This is an alternative to using a devcontainer that
+	// some might find simpler.
+	DockerfilePath string
+	// BuildContextPath can be specified when a DockerfilePath is specified
+	// outside the base WorkspaceFolder. This path MUST be relative to the
+	// WorkspaceFolder path into which the repo is cloned.
+	BuildContextPath string
+	// CacheTTLDays is the number of days to use cached layers before expiring
+	// them. Defaults to 7 days.
+	CacheTTLDays int64
+	// DockerConfigBase64 is the base64 encoded Docker config file that will be
+	// used to pull images from private container registries.
+	DockerConfigBase64 string
+	// FallbackImage specifies an alternative image to use when neither an image
+	// is declared in the devcontainer.json file nor a Dockerfile is present. If
+	// there's a build failure (from a faulty Dockerfile) or a misconfiguration,
+	// this image will be the substitute. Set ExitOnBuildFailure to true to halt
+	// the container if the build faces an issue.
+	FallbackImage string
+	// ExitOnBuildFailure terminates the container upon a build failure. This is
+	// handy when preferring the FALLBACK_IMAGE in cases where no
+	// devcontainer.json or image is provided. However, it ensures that the
+	// container stops if the build process encounters an error.
+	ExitOnBuildFailure bool
+	// ForceSafe ignores any filesystem safety checks. This could cause serious
+	// harm to your system! This is used in cases where bypass is needed to
+	// unblock customers.
+	ForceSafe bool
+	// Insecure bypasses TLS verification when cloning and pulling from container
+	// registries.
+	Insecure bool
+	// IgnorePaths is the comma separated list of paths to ignore when building
+	// the workspace.
+	IgnorePaths []string
+	// SkipRebuild skips building if the MagicFile exists. This is used to skip
+	// building when a container is restarting. e.g. docker stop -> docker start
+	// This value can always be set to true - even if the container is being
+	// started for the first time.
+	SkipRebuild bool
+	// GitURL is the URL of the Git repository to clone. This is optional.
+	GitURL string
+	// GitCloneDepth is the depth to use when cloning the Git repository.
+	GitCloneDepth int64
+	// GitCloneSingleBranch clone only a single branch of the Git repository.
 	GitCloneSingleBranch bool
-	GitUsername          string
-	GitPassword          string
-	GitHTTPProxyURL      string
-	WorkspaceFolder      string
-	SSLCertBase64        string
-	ExportEnvFile        string
-	PostStartScriptPath  string
+	// GitUsername is the username to use for Git authentication. This is
+	// optional.
+	GitUsername string
+	// GitPassword is the password to use for Git authentication. This is
+	// optional.
+	GitPassword string
+	// GitHTTPProxyURL is the URL for the HTTP proxy. This is optional.
+	GitHTTPProxyURL string
+	// WorkspaceFolder is the path to the workspace folder that will be built.
+	// This is optional.
+	WorkspaceFolder string
+	// SSLCertBase64 is the content of an SSL cert file. This is useful for
+	// self-signed certificates.
+	SSLCertBase64 string
+	// ExportEnvFile is the optional file path to a .env file where envbuilder
+	// will dump environment variables from devcontainer.json and the built
+	// container image.
+	ExportEnvFile string
+	// PostStartScriptPath is the path to a script that will be created by
+	// envbuilder based on the postStartCommand in devcontainer.json, if any is
+	// specified (otherwise the script is not created). If this is set, the
+	// specified InitCommand should check for the presence of this script and
+	// execute it after successful startup.
+	PostStartScriptPath string
 	// Logger is the logger to use for all operations.
 	Logger LoggerFunc
-	// Filesystem is the filesystem to use for all operations.
-	// Defaults to the host filesystem.
+	// Filesystem is the filesystem to use for all operations. Defaults to the
+	// host filesystem.
 	Filesystem billy.Filesystem
-	// These options are specifically used when envbuilder
-	// is invoked as part of a Coder workspace.
-	CoderAgentURL       *url.URL
-	CoderAgentToken     string
+	// These options are specifically used when envbuilder is invoked as part of a
+	// Coder workspace.
+	CoderAgentURL *url.URL
+	// CoderAgentToken is the authentication token for a Coder agent.
+	CoderAgentToken string
+	// CoderAgentSubsystem is the Coder agent subsystems to report when forwarding
+	// logs. The envbuilder subsystem is always included.
 	CoderAgentSubsystem []string
 }