create consistency around godoc parsing

admin_organization.go

@@ -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)

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)

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
 }

errors.go

@@ -17,40 +17,38 @@ var (
 )
 
 // Options/fields that cannot be defined
+
 var (
 	ErrUnsupportedOperations = errors.New("operations is deprecated and cannot be specified when execution mode is used")
 
 	ErrUnsupportedPrivateKey = errors.New("private Key can only be present with Azure DevOps Server service provider")
 )
 
 // 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
+
 var (
 	ErrInvalidWorkspaceID = errors.New("invalid value for workspace ID")
 
@@ -134,6 +132,7 @@ var (
 )
 
 // Missing values for required field/option
+
 var (
 	ErrRequiredAccess = errors.New("access is required")
 

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 {

organization_membership.go

@@ -63,6 +63,7 @@ type OrganizationMembership struct {
 	Teams        []*Team       `jsonapi:"relation,teams"`
 }
 
+// A list of relations to include. See available resources
 // https://www.terraform.io/cloud-docs/api-docs/organization-memberships#available-related-resources
 type OrganizationMembershipIncludeOps string
 

organization_tags.go

@@ -9,6 +9,10 @@ import (
 
 var _ OrganizationTags = (*organizationTags)(nil)
 
+// OrganizationMemberships describes all the list of tags used with all resources across the organization.
+//
+// TFE API docs:
+// https://www.terraform.io/cloud-docs/api-docs/organization-tags
 type OrganizationTags interface {
 	// List all tags within an organization
 	List(ctx context.Context, organization string, options *OrganizationTagsListOptions) (*OrganizationTagsList, error)
@@ -20,6 +24,7 @@ type OrganizationTags interface {
 	AddWorkspaces(ctx context.Context, tag string, options AddWorkspacesToTagOptions) error
 }
 
+// organizationTags implements OrganizationTags.
 type organizationTags struct {
 	client *Client
 }
@@ -75,7 +80,7 @@ type OrganizationTagsDeleteOptions struct {
 	IDs []string
 }
 
-// this represents a single tag ID sent over the wire
+// tagID represents a single tag ID sent over the wire
 type tagID struct {
 	ID string `jsonapi:"primary,tags"`
 }
@@ -139,7 +144,7 @@ func (w *AddWorkspacesToTagOptions) valid() error {
 	return nil
 }
 
-// this represents how workspace IDs will be sent over the wire
+// workspaceID represents how workspace IDs will be sent over the wire
 type workspaceID struct {
 	ID string `jsonapi:"primary,workspaces"`
 }

plan.go

@@ -15,7 +15,7 @@ var _ Plans = (*plans)(nil)
 // Plans describes all the plan related methods that the Terraform Enterprise
 // API supports.
 //
-// TFE API docs: https://www.terraform.io/docs/cloud/api/plan.html
+// TFE API docs: https://www.terraform.io/cloud-docs/api-docs/plans
 type Plans interface {
 	// Read a plan by its ID.
 	Read(ctx context.Context, planID string) (*Plan, error)

plan_export.go

@@ -97,6 +97,7 @@ func (o PlanExportCreateOptions) valid() error {
 	return nil
 }
 
+// Create a plan export.
 func (s *planExports) Create(ctx context.Context, options PlanExportCreateOptions) (*PlanExport, error) {
 	if err := options.valid(); err != nil {
 		return nil, err

policy_set.go

@@ -13,7 +13,7 @@ var _ PolicySets = (*policySets)(nil)
 // PolicySets describes all the policy set related methods that the Terraform
 // Enterprise API supports.
 //
-// TFE API docs: https://www.terraform.io/docs/cloud/api/policies.html
+// TFE API docs: https://www.terraform.io/docs/cloud/api/policy-sets.html
 type PolicySets interface {
 	// List all the policy sets for a given organization.
 	List(ctx context.Context, organization string, options *PolicySetListOptions) (*PolicySetList, error)
@@ -186,6 +186,8 @@ func (s *policySets) Create(ctx context.Context, organization string, options Po
 	return ps, err
 }
 
+// A list of relations to include. See available resources
+//https://www.terraform.io/cloud-docs/api-docs/policy-sets#relationships
 type PolicySetIncludeOps string
 
 const (

policy_set_version.go

@@ -64,6 +64,7 @@ type PolicySetVersionStatusTimestamps struct {
 	ErroredAt    time.Time `jsonapi:"attr,errored-at,rfc3339"`
 }
 
+// PolicySetVersion represents a Terraform Enterprise Policy Set Version
 type PolicySetVersion struct {
 	ID               string                           `jsonapi:"primary,policy-set-versions"`
 	Source           PolicySetVersionSource           `jsonapi:"attr,source"`

state_version_output.go

@@ -18,10 +18,12 @@ type StateVersionOutputs interface {
 	Read(ctx context.Context, outputID string) (*StateVersionOutput, error)
 }
 
+// stateVersionOutputs implements StateVersionOutputs.
 type stateVersionOutputs struct {
 	client *Client
 }
 
+// StateVersionOutput represents a State Version Outputs
 type StateVersionOutput struct {
 	ID        string      `jsonapi:"primary,state-version-outputs"`
 	Name      string      `jsonapi:"attr,name"`
@@ -30,6 +32,7 @@ type StateVersionOutput struct {
 	Value     interface{} `jsonapi:"attr,value"`
 }
 
+// Read a State Version Output
 func (s *stateVersionOutputs) Read(ctx context.Context, outputID string) (*StateVersionOutput, error) {
 	if !validStringID(&outputID) {
 		return nil, ErrInvalidRunID

team_access.go

@@ -106,7 +106,6 @@ type TeamAccessListOptions struct {
 	WorkspaceID string `url:"filter[workspace][id]"`
 }
 
-//check that workspaceID field has a valid value
 func (o *TeamAccessListOptions) valid() error {
 	if o == nil {
 		return ErrRequiredTeamAccessListOps