From c0eb830c4233ba4084031947579ca795b4a8e024 Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Mon, 30 Aug 2021 15:53:29 -0700 Subject: [PATCH] better docstrings and regenerate docs --- datasource/packer-image-iteration/data.go | 60 ++++++++++++------- .../DatasourceOutput.mdx | 15 +++-- .../ParBuild-not-required.mdx | 30 ++++++---- .../ParImage-not-required.mdx | 11 ++-- 4 files changed, 76 insertions(+), 40 deletions(-) diff --git a/datasource/packer-image-iteration/data.go b/datasource/packer-image-iteration/data.go index ed29c3d8b..c53065871 100644 --- a/datasource/packer-image-iteration/data.go +++ b/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 { diff --git a/website/content/partials/datasource/packer-image-iteration/DatasourceOutput.mdx b/website/content/partials/datasource/packer-image-iteration/DatasourceOutput.mdx index 1ffe5ce8e..20f15d53a 100644 --- a/website/content/partials/datasource/packer-image-iteration/DatasourceOutput.mdx +++ b/website/content/partials/datasource/packer-image-iteration/DatasourceOutput.mdx @@ -1,11 +1,18 @@ -- `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. diff --git a/website/content/partials/datasource/packer-image-iteration/ParBuild-not-required.mdx b/website/content/partials/datasource/packer-image-iteration/ParBuild-not-required.mdx index b1345e8c9..4ae39c4ac 100644 --- a/website/content/partials/datasource/packer-image-iteration/ParBuild-not-required.mdx +++ b/website/content/partials/datasource/packer-image-iteration/ParBuild-not-required.mdx @@ -1,25 +1,31 @@ -- `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. diff --git a/website/content/partials/datasource/packer-image-iteration/ParImage-not-required.mdx b/website/content/partials/datasource/packer-image-iteration/ParImage-not-required.mdx index 7f2ce1669..fe891d0ed 100644 --- a/website/content/partials/datasource/packer-image-iteration/ParImage-not-required.mdx +++ b/website/content/partials/datasource/packer-image-iteration/ParImage-not-required.mdx @@ -1,12 +1,15 @@ -- `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.