create consistency around godoc usage of comments

CONTRIBUTING.md

@@ -130,7 +130,7 @@ func (s *example) Create(ctx context.Context, organization string, options Examp
 	return r, nil
 }
 
-// A list of relations to include with an example. See available resources:
+// ExampleIncludeOps represents the available options for include query params.
 // https://www.terraform.io/cloud-docs/api-docs/examples#list-examples (replace this URL with the actual documentation URL)
 type ExampleIncludeOps string
 
@@ -142,7 +142,8 @@ const (
 type ExampleListOptions struct {
 	ListOptions
 
-	// A list of relations to include
+	// Optional: A list of relations to include with an example. See available resources:
+	// https://www.terraform.io/cloud-docs/api-docs/examples#list-examples (replace this URL with the actual documentation URL)
 	Include []ExampleIncludeOps `url:"include,omitempty"`
 }
 
@@ -174,6 +175,8 @@ func (s *example) Read(ctx context.Context, exampleID string) (*Example, error)
 
 // ExampleReadOptions represents the set of options for reading an example
 type ExampleReadOptions struct {
+	// Optional: A list of relations to include with an example. See available resources:
+	// https://www.terraform.io/cloud-docs/api-docs/examples#list-examples (replace this URL with the actual documentation URL)
 	Include []RunTaskIncludeOps `url:"include,omitempty"`
 }
 

admin_organization.go

@@ -72,7 +72,7 @@ type AdminOrganizationList struct {
 	Items []*AdminOrganization
 }
 
-// A list of relations to include. See available resources
+// AdminOrgIncludeOps represents the available options for include query params.
 // https://www.terraform.io/docs/cloud/api/admin/organizations.html#available-related-resources
 type AdminOrgIncludeOps string
 
@@ -84,10 +84,11 @@ 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: A list of relations to include. See available resources
+	// https://www.terraform.io/docs/cloud/api/admin/organizations.html#available-related-resources
 	Include []AdminOrgIncludeOps `url:"include,omitempty"`
 }
 
@@ -117,6 +118,7 @@ func (s *adminOrganizations) List(ctx context.Context, options *AdminOrganizatio
 	return orgl, nil
 }
 
+// ListModuleConsumers lists 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 +140,7 @@ func (s *adminOrganizations) ListModuleConsumers(ctx context.Context, organizati
 	return orgl, nil
 }
 
+// Read an organization by its name.
 func (s *adminOrganizations) Read(ctx context.Context, organization string) (*AdminOrganization, error) {
 	if !validStringID(&organization) {
 		return nil, ErrInvalidOrg
@@ -158,6 +161,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 +182,7 @@ func (s *adminOrganizations) Update(ctx context.Context, organization string, op
 	return org, nil
 }
 
+// UpdateModuleConsumers updates 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
 
@@ -61,9 +63,11 @@ const (
 type AdminRunsListOptions struct {
 	ListOptions
 
-	RunStatus string               `url:"filter[status],omitempty"`
-	Query     string               `url:"q,omitempty"`
-	Include   []AdminRunIncludeOps `url:"include,omitempty"`
+	RunStatus string `url:"filter[status],omitempty"`
+	Query     string `url:"q,omitempty"`
+	// Optional: A list of relations to include. See available resources
+	// https://www.terraform.io/cloud-docs/api-docs/admin/runs#available-related-resources
+	Include []AdminRunIncludeOps `url:"include,omitempty"`
 }
 
 // List all the runs of the terraform enterprise installation.
@@ -111,7 +115,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,8 @@ 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,8 @@ 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,8 @@ 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,8 @@ 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)
@@ -77,7 +77,7 @@ type AdminSMTPSettingsUpdateOptions struct {
 	TestEmailAddress *string       `jsonapi:"attr,test-email-address,omitempty"`
 }
 
-// Updat updates the SMTP settings.
+// Update updates the SMTP settings.
 func (a *adminSMTPSettings) Update(ctx context.Context, options AdminSMTPSettingsUpdateOptions) (*AdminSMTPSetting, error) {
 	if err := options.valid(); err != nil {
 		return nil, err

admin_setting_twilio.go

@@ -7,7 +7,8 @@ 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 +77,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

@@ -64,7 +64,7 @@ type AdminUserList struct {
 	Items []*AdminUser
 }
 
-// A list of relations to include. See available resources
+// AdminUserIncludeOps represents the available options for include query params.
 // https://www.terraform.io/docs/cloud/api/admin/users.html#available-related-resources
 type AdminUserIncludeOps string
 
@@ -77,15 +77,17 @@ 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: A list of relations to include. See available resources
+	// https://www.terraform.io/docs/cloud/api/admin/users.html#available-related-resources
 	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"`
 }
@@ -45,7 +46,7 @@ type AdminWorkspace struct {
 	CurrentRun   *Run          `jsonapi:"relation,current-run"`
 }
 
-// A list of relations to include. See available resources
+// AdminWorkspaceIncludeOps represents the available options for include query params.
 // https://www.terraform.io/docs/cloud/api/admin/workspaces.html#available-related-resources
 type AdminWorkspaceIncludeOps string
 
@@ -62,7 +63,8 @@ type AdminWorkspaceListOptions struct {
 	// A query string (partial workspace name) used to filter the results.
 	// https://www.terraform.io/docs/cloud/api/admin/workspaces.html#query-parameters
 	Query string `url:"q,omitempty"`
-
+	// Optional: A list of relations to include. See available resources
+	// https://www.terraform.io/docs/cloud/api/admin/workspaces.html#available-related-resources
 	Include []AdminWorkspaceIncludeOps `url:"include,omitempty"`
 }
 
@@ -72,7 +74,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

@@ -98,7 +98,7 @@ type CVStatusTimestamps struct {
 	StartedAt  time.Time `jsonapi:"attr,started-at,rfc3339"`
 }
 
-// A list of relations to include. See available resources:
+// ConfigurationVersionIncludeOps represents the available options for include query params.
 // https://www.terraform.io/docs/cloud/api/configuration-versions.html#available-related-resources
 type ConfigurationVersionIncludeOps string
 
@@ -109,14 +109,17 @@ const (
 
 // ConfigurationVersionReadOptions represents the options for reading a configuration version.
 type ConfigurationVersionReadOptions struct {
+	// Optional: A list of relations to include. See available resources:
+	// https://www.terraform.io/docs/cloud/api/configuration-versions.html#available-related-resources
 	Include []ConfigurationVersionIncludeOps `url:"include,omitempty"`
 }
 
 // ConfigurationVersionListOptions represents the options for listing
 // configuration versions.
 type ConfigurationVersionListOptions struct {
 	ListOptions
-
+	// Optional: A list of relations to include. See available resources:
+	// https://www.terraform.io/docs/cloud/api/configuration-versions.html#available-related-resources
 	Include []ConfigurationVersionIncludeOps `url:"include,omitempty"`
 }
 
@@ -175,11 +178,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"`
 }