create consistency around godoc usage of comments

admin_organization.go

@@ -84,10 +84,10 @@ const (
 type AdminOrganizationListOptions struct {
 	ListOptions
 
-	// A query string used to filter organizations.
+	// Optional: A query string used to filter organizations.
 	// Any organizations with a name or notification email partially matching this value will be returned.
 	Query string `url:"q,omitempty"`
-
+	// Optional:
 	Include []AdminOrgIncludeOps `url:"include,omitempty"`
 }
 
@@ -117,6 +117,7 @@ func (s *adminOrganizations) List(ctx context.Context, options *AdminOrganizatio
 	return orgl, nil
 }
 
+// List specific organizations in the Terraform Enterprise installation that have permission to use an organization's modules.
 func (s *adminOrganizations) ListModuleConsumers(ctx context.Context, organization string, options *AdminOrganizationListModuleConsumersOptions) (*AdminOrganizationList, error) {
 	if !validStringID(&organization) {
 		return nil, ErrInvalidOrg
@@ -138,6 +139,7 @@ func (s *adminOrganizations) ListModuleConsumers(ctx context.Context, organizati
 	return orgl, nil
 }
 
+// Show an organization by its name.
 func (s *adminOrganizations) Read(ctx context.Context, organization string) (*AdminOrganization, error) {
 	if !validStringID(&organization) {
 		return nil, ErrInvalidOrg
@@ -158,6 +160,7 @@ func (s *adminOrganizations) Read(ctx context.Context, organization string) (*Ad
 	return org, nil
 }
 
+// Update an organization by its name.
 func (s *adminOrganizations) Update(ctx context.Context, organization string, options AdminOrganizationUpdateOptions) (*AdminOrganization, error) {
 	if !validStringID(&organization) {
 		return nil, ErrInvalidOrg
@@ -178,6 +181,7 @@ func (s *adminOrganizations) Update(ctx context.Context, organization string, op
 	return org, nil
 }
 
+// Update an organization to specify a list of organizations that can use modules from the sharing organization's private registry.
 func (s *adminOrganizations) UpdateModuleConsumers(ctx context.Context, organization string, consumerOrganizationIDs []string) error {
 	if !validStringID(&organization) {
 		return ErrInvalidOrg

admin_run.go

@@ -29,6 +29,7 @@ type adminRuns struct {
 	client *Client
 }
 
+// AdminRun represents a run managed by site administrators that gets returned from the Runs Admin API.
 type AdminRun struct {
 	ID               string               `jsonapi:"primary,runs"`
 	CreatedAt        time.Time            `jsonapi:"attr,created-at,iso8601"`
@@ -47,6 +48,7 @@ type AdminRunsList struct {
 	Items []*AdminRun
 }
 
+// AdminRunIncludeOps represents the available options for include query params
 // https://www.terraform.io/cloud-docs/api-docs/admin/runs#available-related-resources
 type AdminRunIncludeOps string
 
@@ -111,7 +113,6 @@ func (s *adminRuns) ForceCancel(ctx context.Context, runID string, options Admin
 	return s.client.do(ctx, req, nil)
 }
 
-// Check that the field RunStatus has a valid string value
 func (o *AdminRunsListOptions) valid() error {
 	if o == nil { // no need to validate fields
 		return nil

admin_setting.go

@@ -4,7 +4,6 @@ package tfe
 // Note that admin settings are only available in Terraform Enterprise.
 //
 // TFE API docs: https://www.terraform.io/docs/cloud/api/admin/settings.html
-// AdminSettings todo
 type AdminSettings struct {
 	General        GeneralSettings
 	SAML           SAMLSettings

admin_setting_cost_estimation.go

@@ -7,7 +7,7 @@ import (
 // Compile-time proof of interface implementation.
 var _ CostEstimationSettings = (*adminCostEstimationSettings)(nil)
 
-// CostEstimationSettings describes all the cost estimation admin settings.
+// CostEstimationSettings describes all the cost estimation admin settings for the Admin Setting API https://www.terraform.io/cloud-docs/api-docs/admin/settings
 type CostEstimationSettings interface {
 	// Read returns the cost estimation settings.
 	Read(ctx context.Context) (*AdminCostEstimationSetting, error)

admin_setting_customization.go

@@ -20,7 +20,7 @@ type adminCustomizationSettings struct {
 	client *Client
 }
 
-// AdminCustomizationSetting represents the Customization settings in Terraform Enterprise.
+// AdminCustomizationSetting represents the Customization settings in Terraform Enterprise for the Admin Settings API https://www.terraform.io/cloud-docs/api-docs/admin/settings
 type AdminCustomizationSetting struct {
 	ID           string `jsonapi:"primary,customization-settings"`
 	SupportEmail string `jsonapi:"attr,support-email-address"`

admin_setting_general.go

@@ -7,7 +7,7 @@ import (
 // Compile-time proof of interface implementation.
 var _ GeneralSettings = (*adminGeneralSettings)(nil)
 
-// GeneralSettings describes the general admin settings.
+// GeneralSettings describes the general admin settings for the Admin Setting API https://www.terraform.io/cloud-docs/api-docs/admin/settings
 type GeneralSettings interface {
 	// Read returns the general settings
 	Read(ctx context.Context) (*AdminGeneralSetting, error)

admin_setting_saml.go

@@ -7,7 +7,7 @@ import (
 // Compile-time proof of interface implementation.
 var _ SAMLSettings = (*adminSAMLSettings)(nil)
 
-// SAMLSettings describes all the SAML admin settings.
+// SAMLSettings describes all the SAML admin settings for the Admin Setting API https://www.terraform.io/cloud-docs/api-docs/admin/settings
 type SAMLSettings interface {
 	// Read returns the SAML settings.
 	Read(ctx context.Context) (*AdminSAMLSetting, error)

admin_setting_smtp.go

@@ -7,7 +7,7 @@ import (
 // Compile-time proof of interface implementation.
 var _ SMTPSettings = (*adminSMTPSettings)(nil)
 
-// SMTPSettings describes all the SMTP admin settings.
+// SMTPSettings describes all the SMTP admin settings for the Admin Setting API https://www.terraform.io/cloud-docs/api-docs/admin/settings.
 type SMTPSettings interface {
 	// Read returns the SMTP settings.
 	Read(ctx context.Context) (*AdminSMTPSetting, error)

admin_setting_twilio.go

@@ -7,7 +7,7 @@ import (
 // Compile-time proof of interface implementation.
 var _ TwilioSettings = (*adminTwilioSettings)(nil)
 
-// TwilioSettings describes all the Twilio admin settings.
+// TwilioSettings describes all the Twilio admin settings for the Admin Setting API https://www.terraform.io/cloud-docs/api-docs/admin/settings.
 type TwilioSettings interface {
 	// Read returns the Twilio settings.
 	Read(ctx context.Context) (*AdminTwilioSetting, error)
@@ -76,6 +76,7 @@ func (a *adminTwilioSettings) Update(ctx context.Context, options AdminTwilioSet
 // AdminTwilioSettingsVerifyOptions represents the test number to verify Twilio.
 // https://www.terraform.io/docs/cloud/api/admin/settings.html#verify-twilio-settings
 type AdminTwilioSettingsVerifyOptions struct {
+	// Required:
 	TestNumber *string `jsonapi:"attr,test-number"`
 }
 

admin_terraform_version.go

@@ -57,10 +57,10 @@ type AdminTerraformVersion struct {
 type AdminTerraformVersionsListOptions struct {
 	ListOptions
 
-	// A query string to find an exact version
+	// Optional: A query string to find an exact version
 	Filter string `url:"filter[version],omitempty"`
 
-	// A search query string to find all versions that match version substring
+	// Optional: A search query string to find all versions that match version substring
 	Search string `url:"search[version],omitempty"`
 }
 
@@ -110,9 +110,12 @@ func (a *adminTerraformVersions) Read(ctx context.Context, id string) (*AdminTer
 // AdminTerraformVersionCreateOptions for creating a terraform version.
 // https://www.terraform.io/docs/cloud/api/admin/terraform-versions.html#request-body
 type AdminTerraformVersionCreateOptions struct {
-	Type             string  `jsonapi:"primary,terraform-versions"`
-	Version          *string `jsonapi:"attr,version"`
-	URL              *string `jsonapi:"attr,url"`
+	Type string `jsonapi:"primary,terraform-versions"`
+	// Required:
+	Version *string `jsonapi:"attr,version"`
+	// Required:
+	URL *string `jsonapi:"attr,url"`
+	// Required:
 	Sha              *string `jsonapi:"attr,sha"`
 	Official         *bool   `jsonapi:"attr,official,omitempty"`
 	Deprecated       *bool   `jsonapi:"attr,deprecated,omitempty"`

admin_user.go

@@ -77,15 +77,16 @@ const (
 type AdminUserListOptions struct {
 	ListOptions
 
-	// A search query string. Users are searchable by username and email address.
+	// Optional: A search query string. Users are searchable by username and email address.
 	Query string `url:"q,omitempty"`
 
-	// Can be "true" or "false" to show only administrators or non-administrators.
+	// Optional: Can be "true" or "false" to show only administrators or non-administrators.
 	Administrators string `url:"filter[admin],omitempty"`
 
-	// Can be "true" or "false" to show only suspended users or users who are not suspended.
+	// Optional: Can be "true" or "false" to show only suspended users or users who are not suspended.
 	SuspendedUsers string `url:"filter[suspended],omitempty"`
 
+	// Optional:
 	Include []AdminUserIncludeOps `url:"include,omitempty"`
 }
 

admin_workspace.go

@@ -24,11 +24,12 @@ type AdminWorkspaces interface {
 	Delete(ctx context.Context, workspaceID string) error
 }
 
-// adminWorkspaces implements AdminWorkspaces.
+// adminWorkspaces implements AdminWorkspaces interface.
 type adminWorkspaces struct {
 	client *Client
 }
 
+// AdminVCSRepo represents a VCS repository
 type AdminVCSRepo struct {
 	Identifier string `jsonapi:"attr,identifier"`
 }
@@ -72,7 +73,7 @@ type AdminWorkspaceList struct {
 	Items []*AdminWorkspace
 }
 
-// List all the workspaces within a worksapce.
+// List all the workspaces within a workspace.
 func (s *adminWorkspaces) List(ctx context.Context, options *AdminWorkspaceListOptions) (*AdminWorkspaceList, error) {
 	u := "admin/workspaces"
 	req, err := s.client.newRequest("GET", u, options)

agent_pool.go

@@ -84,7 +84,7 @@ type AgentPoolCreateOptions struct {
 	// https://jsonapi.org/format/#crud-creating
 	Type string `jsonapi:"primary,agent-pools"`
 
-	// A name to identify the agent pool.
+	// Required: A name to identify the agent pool.
 	Name *string `jsonapi:"attr,name"`
 }
 

apply.go

@@ -23,7 +23,7 @@ type Applies interface {
 	Logs(ctx context.Context, applyID string) (io.Reader, error)
 }
 
-// applies implements Applys.
+// applies implements Applies interface.
 type applies struct {
 	client *Client
 }

configuration_version.go

@@ -175,11 +175,11 @@ type ConfigurationVersionCreateOptions struct {
 	// https://jsonapi.org/format/#crud-creating
 	Type string `jsonapi:"primary,configuration-versions"`
 
-	// When true, runs are queued automatically when the configuration version
+	// Optional: When true, runs are queued automatically when the configuration version
 	// is uploaded.
 	AutoQueueRuns *bool `jsonapi:"attr,auto-queue-runs,omitempty"`
 
-	// When true, this configuration version can only be used for planning.
+	// Optional: When true, this configuration version can only be used for planning.
 	Speculative *bool `jsonapi:"attr,speculative,omitempty"`
 }
 

errors.go

@@ -25,29 +25,23 @@ var (
 
 // Library errors that usually indicate a bug in the implementation of go-tfe
 var (
-	// ErrItemsMustBeSlice is returned when an API response attribute called Items is not a slice
-	ErrItemsMustBeSlice = errors.New(`model field "Items" must be a slice`)
+	ErrItemsMustBeSlice = errors.New(`model field "Items" must be a slice`) // ErrItemsMustBeSlice is returned when an API response attribute called Items is not a slice
 
-	// ErrInvalidRequestBody is returned when a request body for DELETE/PATCH/POST is not a reference type
-	ErrInvalidRequestBody = errors.New("go-tfe bug: DELETE/PATCH/POST body must be nil, ptr, or ptr slice")
+	ErrInvalidRequestBody = errors.New("go-tfe bug: DELETE/PATCH/POST body must be nil, ptr, or ptr slice") // ErrInvalidRequestBody is returned when a request body for DELETE/PATCH/POST is not a reference type
 
-	// ErrInvalidStructFormat is returned when a mix of json and jsonapi tagged fields are used in the same struct
-	ErrInvalidStructFormat = errors.New("go-tfe bug: struct can't use both json and jsonapi attributes")
+	ErrInvalidStructFormat = errors.New("go-tfe bug: struct can't use both json and jsonapi attributes") // ErrInvalidStructFormat is returned when a mix of json and jsonapi tagged fields are used in the same struct
 )
 
 // Resource Errors
 var (
-	// ErrWorkspaceLocked is returned when trying to lock a
+	ErrWorkspaceLocked = errors.New("workspace already locked") // ErrWorkspaceLocked is returned when trying to lock a
 	// locked workspace.
-	ErrWorkspaceLocked = errors.New("workspace already locked")
 
-	// ErrWorkspaceNotLocked is returned when trying to unlock
+	ErrWorkspaceNotLocked = errors.New("workspace already unlocked") // ErrWorkspaceNotLocked is returned when trying to unlock
 	// a unlocked workspace.
-	ErrWorkspaceNotLocked = errors.New("workspace already unlocked")
 
-	// ErrWorkspaceLockedByRun is returned when trying to unlock a
+	ErrWorkspaceLockedByRun = errors.New("unable to unlock workspace locked by run") // ErrWorkspaceLockedByRun is returned when trying to unlock a
 	// workspace locked by a run
-	ErrWorkspaceLockedByRun = errors.New("unable to unlock workspace locked by run")
 )
 
 // Invalid values for resources/struct fields

ip_ranges.go

@@ -22,10 +22,12 @@ type IPRanges interface {
 	Read(ctx context.Context, modifiedSince string) (*IPRange, error)
 }
 
+// ipRanges implements IPRanges interface.
 type ipRanges struct {
 	client *Client
 }
 
+// IPRange represents a list of Terraform Cloud's IP ranges
 type IPRange struct {
 	// List of IP ranges in CIDR notation used for connections from user site to Terraform Cloud APIs
 	API []string `json:"api"`
@@ -37,6 +39,7 @@ type IPRange struct {
 	VCS []string `json:"vcs"`
 }
 
+// Read an IPRange that was not modified since the specified date.
 func (i *ipRanges) Read(ctx context.Context, modifiedSince string) (*IPRange, error) {
 	req, err := i.client.newRequest("GET", "/api/meta/ip-ranges", nil)
 	if err != nil {

notification_configuration.go

@@ -40,7 +40,6 @@ type notificationConfigurations struct {
 	client *Client
 }
 
-// List of available notification triggers.
 const (
 	NotificationTriggerCreated        string = "run:created"
 	NotificationTriggerPlanning       string = "run:planning"
@@ -135,29 +134,29 @@ type NotificationConfigurationCreateOptions struct {
 	// https://jsonapi.org/format/#crud-creating
 	Type string `jsonapi:"primary,notification-configurations"`
 
-	// The destination type of the notification configuration
+	// Required: The destination type of the notification configuration
 	DestinationType *NotificationDestinationType `jsonapi:"attr,destination-type"`
 
-	// Whether the notification configuration should be enabled or not
+	// Required: Whether the notification configuration should be enabled or not
 	Enabled *bool `jsonapi:"attr,enabled"`
 
-	// The name of the notification configuration
+	// Required: The name of the notification configuration
 	Name *string `jsonapi:"attr,name"`
 
-	// The token of the notification configuration
+	// Optional: The token of the notification configuration
 	Token *string `jsonapi:"attr,token,omitempty"`
 
-	// The list of run events that will trigger notifications.
+	// Optional: The list of run events that will trigger notifications.
 	Triggers []string `jsonapi:"attr,triggers,omitempty"`
 
-	// The url of the notification configuration
+	// Optional: The url of the notification configuration
 	URL *string `jsonapi:"attr,url,omitempty"`
 
-	// The list of email addresses that will receive notification emails.
+	// Optional: The list of email addresses that will receive notification emails.
 	// EmailAddresses is only available for TFE users. It is not available in TFC.
 	EmailAddresses []string `jsonapi:"attr,email-addresses,omitempty"`
 
-	// The list of users belonging to the organization that will receive notification emails.
+	// Optional: The list of users belonging to the organization that will receive notification emails.
 	EmailUsers []*User `jsonapi:"relation,users,omitempty"`
 }
 
@@ -234,26 +233,26 @@ type NotificationConfigurationUpdateOptions struct {
 	// https://jsonapi.org/format/#crud-creating
 	Type string `jsonapi:"primary,notification-configurations"`
 
-	// Whether the notification configuration should be enabled or not
+	// Optional: Whether the notification configuration should be enabled or not
 	Enabled *bool `jsonapi:"attr,enabled,omitempty"`
 
-	// The name of the notification configuration
+	// Optional: The name of the notification configuration
 	Name *string `jsonapi:"attr,name,omitempty"`
 
-	// The token of the notification configuration
+	// Optional: The token of the notification configuration
 	Token *string `jsonapi:"attr,token,omitempty"`
 
-	// The list of run events that will trigger notifications.
+	// Optional: The list of run events that will trigger notifications.
 	Triggers []string `jsonapi:"attr,triggers,omitempty"`
 
-	// The url of the notification configuration
+	// Optional: The url of the notification configuration
 	URL *string `jsonapi:"attr,url,omitempty"`
 
-	// The list of email addresses that will receive notification emails.
+	// Optional: The list of email addresses that will receive notification emails.
 	// EmailAddresses is only available for TFE users. It is not available in TFC.
 	EmailAddresses []string `jsonapi:"attr,email-addresses,omitempty"`
 
-	// The list of users belonging to the organization that will receive notification emails.
+	// Optional: The list of users belonging to the organization that will receive notification emails.
 	EmailUsers []*User `jsonapi:"relation,users,omitempty"`
 }