adds Stack godocs

hashicorp · Jul 18, 2024 · 30cc1ac · 30cc1ac
1 parent 0654890
commit 30cc1ac
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 2 deletions.
diff --git a/stack.go b/stack.go
@@ -89,6 +89,7 @@ type Stack struct {
 	LatestStackConfiguration *StackConfiguration `jsonapi:"relation,latest-stack-configuration"`
 }
 
+// StackConfigurationStatusTimestamps represents the timestamps for a stack configuration
 type StackConfigurationStatusTimestamps struct {
 	QueuedAt     *time.Time `jsonapi:"attr,queued-at,omitempty,rfc3339"`
 	CompletedAt  *time.Time `jsonapi:"attr,completed-at,omitempty,rfc3339"`
@@ -98,12 +99,14 @@ type StackConfigurationStatusTimestamps struct {
 	ErroredAt    *time.Time `jsonapi:"attr,errored-at,omitempty,rfc3339"`
 }
 
+// StackComponent represents a stack component, specified by configuration
 type StackComponent struct {
 	Name       string `json:"name"`
 	Correlator string `json:"correlator"`
 	Expanded   bool   `json:"expanded"`
 }
 
+// StackConfiguration represents a stack configuration snapshot
 type StackConfiguration struct {
 	// Attributes
 	ID                   string                              `jsonapi:"primary,stack-configurations"`
@@ -117,6 +120,7 @@ type StackConfiguration struct {
 	EventStreamURL       string                              `jsonapi:"attr,event-stream-url"`
 }
 
+// StackDeployment represents a stack deployment, specified by configuration
 type StackDeployment struct {
 	// Attributes
 	ID            string    `jsonapi:"primary,stack-deployments"`
@@ -131,6 +135,7 @@ type StackDeployment struct {
 	CurrentStackState *StackState `jsonapi:"relation,current-stack-state"`
 }
 
+// StackState represents a stack state
 type StackState struct {
 	// Attributes
 	ID string `jsonapi:"primary,stack-states"`
@@ -161,7 +166,8 @@ type StackUpdateOptions struct {
 	VCSRepo     *StackVCSRepo `jsonapi:"attr,vcs-repo,omitempty"`
 }
 
-func (s stacks) UpdateConfiguration(ctx context.Context, stackID string) (*Stack, error) {
+// UpdateConfiguration updates the configuration of a stack, triggering stack operations
+func (s *stacks) UpdateConfiguration(ctx context.Context, stackID string) (*Stack, error) {
 	req, err := s.client.NewRequest("POST", fmt.Sprintf("stacks/%s/actions/update-configuration", url.PathEscape(stackID)), nil)
 	if err != nil {
 		return nil, err
@@ -176,6 +182,7 @@ func (s stacks) UpdateConfiguration(ctx context.Context, stackID string) (*Stack
 	return stack, nil
 }
 
+// List returns a list of stacks, optionally filtered by additional paameters.
 func (s stacks) List(ctx context.Context, organization string, options *StackListOptions) (*StackList, error) {
 	if err := options.valid(); err != nil {
 		return nil, err
@@ -195,6 +202,7 @@ func (s stacks) List(ctx context.Context, organization string, options *StackLis
 	return sl, nil
 }
 
+// Read returns a stack by its ID.
 func (s stacks) Read(ctx context.Context, stackID string) (*Stack, error) {
 	req, err := s.client.NewRequest("GET", fmt.Sprintf("stacks/%s", url.PathEscape(stackID)), nil)
 	if err != nil {
@@ -210,6 +218,7 @@ func (s stacks) Read(ctx context.Context, stackID string) (*Stack, error) {
 	return stack, nil
 }
 
+// Create creates a new stack.
 func (s stacks) Create(ctx context.Context, options StackCreateOptions) (*Stack, error) {
 	if err := options.valid(); err != nil {
 		return nil, err
@@ -229,6 +238,7 @@ func (s stacks) Create(ctx context.Context, options StackCreateOptions) (*Stack,
 	return stack, nil
 }
 
+// Update updates a stack.
 func (s stacks) Update(ctx context.Context, stackID string, options StackUpdateOptions) (*Stack, error) {
 	req, err := s.client.NewRequest("PATCH", fmt.Sprintf("stacks/%s", url.PathEscape(stackID)), &options)
 	if err != nil {
@@ -244,6 +254,7 @@ func (s stacks) Update(ctx context.Context, stackID string, options StackUpdateO
 	return stack, nil
 }
 
+// Delete deletes a stack.
 func (s stacks) Delete(ctx context.Context, stackID string) error {
 	req, err := s.client.NewRequest("POST", fmt.Sprintf("stacks/%s/delete", url.PathEscape(stackID)), nil)
 	if err != nil {

diff --git a/stack_integration_test.go b/stack_integration_test.go
@@ -234,7 +234,7 @@ func pollStackDeploymentStatus(t *testing.T, ctx context.Context, client *Client
 			var err error
 			deployment, err := client.StackDeployments.Read(ctx, stackID, deploymentName)
 			if err != nil {
-				t.Fatalf("Failed to read stack %q: %s", stackID, err)
+				t.Fatalf("Failed to read stack deployment %s/%s: %s", stackID, deploymentName, err)
 			}
 
 			t.Logf("Stack deployment %s/%s had status %q", stackID, deploymentName, deployment.Status)