better docstrings and regenerate docs

datasource/packer-image-iteration/data.go

@@ -60,49 +60,69 @@ func (d *Datasource) Configure(raws ...interface{}) error {
 // Copy of []*models.HashicorpCloudPackerBuild. Need to copy so we can generate
 // the HCL spec.
 type ParBuild struct {
-	// aws
+	// The name of the cloud provider that the build exists in. For example,
+	// "aws", "azure", or "gce".
 	CloudProvider string `mapstructure:"cloud_provider"`
-	// builder or post-processor used to build this
+	// The specific Packer builder or post-processor used to create the build.
 	ComponentType string `mapstructure:"component_type"`
-	// created at
-	// Format: date-time
+	// The date and time at which the build was run.
 	CreatedAt string `mapstructure:"created_at"`
-	// ULID
+	// The build id. This is a ULID, which is a unique identifier similar
+	// to a UUID. It is created by the HCP Packer Registry when an build is
+	// first created, and is unique to this build.
 	ID string `mapstructure:"id"`
-	// images
+	// A list of images as stored in the HCP Packer registry. See the ParImage
+	// docs for more information.
 	Images []ParImage `mapstructure:"images"`
-	// ULID of the iteration
+	// The iteration id. This is a ULID, which is a unique identifier similar
+	// to a UUID. It is created by the HCP Packer Registry when an iteration is
+	// first created, and is unique to this iteration.
 	IterationID string `mapstructure:"iteration_id"`
-	// unstructured metadata
+	// Unstructured key:value metadata associated with the build.
 	Labels map[string]string `mapstructure:"labels"`
-	// packer run uuid
+	// The UUID associated with the Packer run that created this build.
 	PackerRunUUID string `mapstructure:"packer_run_uuid"`
-	// complete
+	// Whether the build is considered "complete" (the Packer build ran
+	// successfully and created an artifact), or "incomplete" (the Packer
+	// build did not finish, and there is no uploaded artifact).
 	Status string `mapstructure:"status"`
-	// updated at
-	// Format: date-time
+	// The date and time at which the build was last updated.
 	UpdatedAt string `mapstructure:"updated_at"`
 }
 
 // Copy of []*models.HashicorpCloudPackerImage Need to copy so we can generate
 // the HCL spec.
 type ParImage struct {
-	// Timestamp at which this image was created
-	// Format: date-time
+	// The date and time at which the build was last updated.
 	CreatedAt string `mapstructure:"created_at,omitempty"`
-	// ULID for the image
+	// The iteration id. This is a ULID, which is a unique identifier similar
+	// to a UUID. It is created by the HCP Packer Registry when an iteration is
+	// first created, and is unique to this iteration.
 	ID string `mapstructure:"id,omitempty"`
 	// ID or URL of the remote cloud image as given by a build.
 	ImageID string `mapstructure:"image_id,omitempty"`
-	// region as given by `packer build`. eg. "ap-east-1"
+	// The cloud region as given by `packer build`. eg. "ap-east-1".
+	// For locally managed clouds, this may map instead to a cluster, server
+	// or datastore.
 	Region string `mapstructure:"region,omitempty"`
 }
 
 type DatasourceOutput struct {
-	Id                 string     `mapstructure:"Id"`
-	IncrementalVersion int32      `mapstructure:"incremental_version"`
-	CreatedAt          string     `mapstructure:"created_at"`
-	Builds             []ParBuild `mapstructure:"builds"`
+	// The iteration id. This is a ULID, which is a unique identifier similar
+	// to a UUID. It is created by the HCP Packer Registry when an iteration is
+	// first created, and is unique to this iteration.
+	Id string `mapstructure:"Id"`
+	// The version number assigned to an iteration. This number is an integer,
+	// and is created by the HCP Packer Registry once an iteration is
+	// marked "complete". If a new iteration is marked "complete", the version
+	// that HCP Packer assigns to it will always be the highest previous
+	// iteration version plus one.
+	IncrementalVersion int32 `mapstructure:"incremental_version"`
+	// The date the iteration was created.
+	CreatedAt string `mapstructure:"created_at"`
+	// A list of builds that are stored in the iteration. These builds can be
+	// parsed using HCL to find individual image ids for specific providers.
+	Builds []ParBuild `mapstructure:"builds"`
 }
 
 func (d *Datasource) OutputSpec() hcldec.ObjectSpec {

website/content/partials/datasource/packer-image-iteration/DatasourceOutput.mdx

@@ -1,11 +1,18 @@
 <!-- Code generated from the comments of the DatasourceOutput struct in datasource/packer-image-iteration/data.go; DO NOT EDIT MANUALLY -->
 
-- `Id` (string) - Id
+- `Id` (string) - The iteration id. This is a ULID, which is a unique identifier similar
+  to a UUID. It is created by the HCP Packer Registry when an iteration is
+  first created, and is unique to this iteration.
 
-- `incremental_version` (int32) - Incremental Version
+- `incremental_version` (int32) - The version number assigned to an iteration. This number is an integer,
+  and is created by the HCP Packer Registry once an iteration is
+  marked "complete". If a new iteration is marked "complete", the version
+  that HCP Packer assigns to it will always be the highest previous
+  iteration version plus one.
 
-- `created_at` (string) - Created At
+- `created_at` (string) - The date the iteration was created.
 
-- `builds` ([]ParBuild) - Builds
+- `builds` ([]ParBuild) - A list of builds that are stored in the iteration. These builds can be
+  parsed using HCL to find individual image ids for specific providers.
 
 <!-- End of code generated from the comments of the DatasourceOutput struct in datasource/packer-image-iteration/data.go; -->

website/content/partials/datasource/packer-image-iteration/ParBuild-not-required.mdx

@@ -1,25 +1,31 @@
 <!-- Code generated from the comments of the ParBuild struct in datasource/packer-image-iteration/data.go; DO NOT EDIT MANUALLY -->
 
-- `cloud_provider` (string) - aws
+- `cloud_provider` (string) - The name of the cloud provider that the build exists in. For example,
+  "aws", "azure", or "gce".
 
-- `component_type` (string) - builder or post-processor used to build this
+- `component_type` (string) - The specific Packer builder or post-processor used to create the build.
 
-- `created_at` (string) - created at
-  Format: date-time
+- `created_at` (string) - The date and time at which the build was run.
 
-- `id` (string) - ULID
+- `id` (string) - The build id. This is a ULID, which is a unique identifier similar
+  to a UUID. It is created by the HCP Packer Registry when an build is
+  first created, and is unique to this build.
 
-- `images` ([]ParImage) - images
+- `images` ([]ParImage) - A list of images as stored in the HCP Packer registry. See the ParImage
+  docs for more information.
 
-- `iteration_id` (string) - ULID of the iteration
+- `iteration_id` (string) - The iteration id. This is a ULID, which is a unique identifier similar
+  to a UUID. It is created by the HCP Packer Registry when an iteration is
+  first created, and is unique to this iteration.
 
-- `labels` (map[string]string) - unstructured metadata
+- `labels` (map[string]string) - Unstructured key:value metadata associated with the build.
 
-- `packer_run_uuid` (string) - packer run uuid
+- `packer_run_uuid` (string) - The UUID associated with the Packer run that created this build.
 
-- `status` (string) - complete
+- `status` (string) - Whether the build is considered "complete" (the Packer build ran
+  successfully and created an artifact), or "incomplete" (the Packer
+  build did not finish, and there is no uploaded artifact).
 
-- `updated_at` (string) - updated at
-  Format: date-time
+- `updated_at` (string) - The date and time at which the build was last updated.
 
 <!-- End of code generated from the comments of the ParBuild struct in datasource/packer-image-iteration/data.go; -->

website/content/partials/datasource/packer-image-iteration/ParImage-not-required.mdx

@@ -1,12 +1,15 @@
 <!-- Code generated from the comments of the ParImage struct in datasource/packer-image-iteration/data.go; DO NOT EDIT MANUALLY -->
 
-- `created_at` (string) - Timestamp at which this image was created
-  Format: date-time
+- `created_at` (string) - The date and time at which the build was last updated.
 
-- `id` (string) - ULID for the image
+- `id` (string) - The iteration id. This is a ULID, which is a unique identifier similar
+  to a UUID. It is created by the HCP Packer Registry when an iteration is
+  first created, and is unique to this iteration.
 
 - `image_id` (string) - ID or URL of the remote cloud image as given by a build.
 
-- `region` (string) - region as given by `packer build`. eg. "ap-east-1"
+- `region` (string) - The cloud region as given by `packer build`. eg. "ap-east-1".
+  For locally managed clouds, this may map instead to a cluster, server
+  or datastore.
 
 <!-- End of code generated from the comments of the ParImage struct in datasource/packer-image-iteration/data.go; -->