create consistency around godoc parsing #331

uturunku1 · 2022-02-24T00:38:18Z

Description

The goal for this PR is to get the godocs ready for 1.0

There's a bit of inconsistency with the docs, where certain patterns are used for some resources and others deviate from the pattern. To mention a few:

Linking the API docs for the resource when documenting the resource interface
Denoting which fields are required/optional in create, list, update option structs.
Some option structs include docs for each field, others do not
A couple of interfaces have the wrong link to API docs
GoDocs is randomly parsing some of our variables and constants: https://pkg.go.dev/github.com/hashicorp/go-tfe#pkg-constants As you see is only showing the ones defined in organization_membership.go and notification_configuration.go because they just happen to have a comment on top which is what godoc uses to parse and display.

Implementation and rules:

All interfaces must have a comment with a link to the API doc related to it.
All methods for this interface must have a explanation on top of the definition of the method
Helper functions must not have explanation on top of its definition
Variables and functions for internal usage (like the ones on tfe.go) do not need to be documented in GoDoc. This can be avoided by:

Having the variables/constants lowercase or prefix with underscore. GoDoc only displays the ones that are uppercase.
Adding a space in between the declaration and the comment. GoDoc does not parse comments that are not adjacent to a top-level declaration and will be omitted from godoc’s output

More rules around GoDoc can be found here: https://go.dev/blog/godoc
And their source code can be found here: https://github.com/golang/tools/tree/master/godoc
You can also see how their own source code gets parsed here https://pkg.go.dev/golang.org/x/tools@v0.1.9/godoc

Constants that are typed such as

const (
	Advisory  TaskEnforcementLevel = "advisory"
	Mandatory TaskEnforcementLevel = "mandatory"
)

must be sitting next to the declaration of the type like this:

//TaskEnforcementLevel is an enum that describes the enforcement levels for a run task
type TaskEnforcementLevel string

const (
	Advisory  TaskEnforcementLevel = "advisory"
	Mandatory TaskEnforcementLevel = "mandatory"
)

That way GoDoc can document the type and the constants available to this type as a single group. If they are not sitting next to each other, for example in this case:

//TaskEnforcementLevel is an enum that describes the enforcement levels for a run task
type TaskEnforcementLevel string

const (
	TaskPassed      TaskResultStatus = "passed"
	TaskFailed      TaskResultStatus = "failed"

	Advisory  TaskEnforcementLevel = "advisory"
	Mandatory TaskEnforcementLevel = "mandatory"
)

Then GoDoc will not make the connection between those two and will documented them separately.

Testing plan

These changes were tested by installing godoc locally and running godoc -http=:6060

External links

Output from tests (HashiCorp employees only)

$ TFE_ADDRESS="https://example" TFE_TOKEN="example" TF_ACC="1" go test ./... -v -tags=integration -run TestFunctionsAffectedByChange

...

task_stages_integration_test.go

uturunku1 · 2022-02-24T17:36:41Z

team_access.go

-type SentinelMocksPermissionType string
-
-// WorkspaceLockingPermissionType represents the permissiontype to lock or unlock a workspace.
-type WorkspaceLockingPermissionType bool


I deleted this type WorkspaceLockingPermissionType. It was not being used anywhere

uturunku1 · 2022-02-24T19:58:42Z

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


FYI, this is not suppose to be plans.html . This would take you to a "page not found"

brandonc

👇

brandonc · 2022-02-24T23:09:35Z

admin_organization.go

 	// Any organizations with a name or notification email partially matching this value will be returned.
 	Query string `url:"q,omitempty"`
-
+	// Optional:


Include is an interesting and useful parameter that I think we should take better care to document explicitly. Here's an example from WorkspaceReadOptions:

// Optional: A list of relations to include. See available resources https://www.terraform.io/docs/cloud/api/workspaces.html#available-related-resources

I think we have good docs around which relations are possible to include, and a link would reinforce the relationship we now have to maintain because they are typed strings.

We have a similar comment for the include options in admin_organization.go. You may have not seen it because is in line 75:

// A list of relations to include. See available resources // https://www.terraform.io/docs/cloud/api/admin/organizations.html#available-related-resources type AdminOrgIncludeOps string

So, the issue here is that we have discrepancy where we place that comment and link. Most of the time we do it on top of the type and occasionally we do it at the include field definition level, like what you see in workspace.go. I personally like it a bit more on top of the type declaration because Godoc makes types more visible and will include the typed constants for the include field.

brandonc · 2022-02-24T23:26:17Z

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.


I think the godoc convention is to begin the comment with the element it describes:

"ListModuleConsumers lists specific organizations..."

👆 I noticed there were several comments for functions that don't follow the pattern: // <FUNCTION> does X and Y -- something to keep an eye out for.

I have not ran into that issue before, but I will keep an eye on that.

sebasslash · 2022-02-25T18:56:21Z

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.


So I'm curious if we should move the link to a new line for readability.

uturunku1 force-pushed the update-GoDoc branch from 03e2e14 to 9ff2a5d Compare February 24, 2022 00:49

uturunku1 commented Feb 24, 2022

View reviewed changes

task_stages_integration_test.go Outdated Show resolved Hide resolved

uturunku1 commented Feb 24, 2022

View reviewed changes

uturunku1 marked this pull request as ready for review February 24, 2022 18:31

uturunku1 force-pushed the update-GoDoc branch from bbba200 to c5c0205 Compare February 24, 2022 18:34

uturunku1 added the release-1.0 label Feb 24, 2022

uturunku1 force-pushed the update-GoDoc branch from c5c0205 to bae2150 Compare February 24, 2022 19:53

uturunku1 commented Feb 24, 2022

View reviewed changes

uturunku1 force-pushed the update-GoDoc branch from bae2150 to 5dc34ca Compare February 24, 2022 21:46

brandonc reviewed Feb 24, 2022

View reviewed changes

uturunku1 force-pushed the update-GoDoc branch 2 times, most recently from 47eccc9 to b6e52e5 Compare February 25, 2022 18:46

sebasslash reviewed Feb 25, 2022

View reviewed changes

uturunku1 force-pushed the update-GoDoc branch from 6cc8a5e to eb88cd1 Compare February 25, 2022 22:00

create consistency around godoc usage of comments

5b6e0f6

uturunku1 force-pushed the update-GoDoc branch from eb88cd1 to 5b6e0f6 Compare February 26, 2022 00:29

brandonc approved these changes Feb 28, 2022

View reviewed changes

uturunku1 merged commit c0c4937 into releases-1.0.x Feb 28, 2022

uturunku1 deleted the update-GoDoc branch February 28, 2022 18:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

create consistency around godoc parsing #331

create consistency around godoc parsing #331

uturunku1 commented Feb 24, 2022 •

edited

uturunku1 Feb 24, 2022 •

edited

uturunku1 Feb 24, 2022

brandonc left a comment

brandonc Feb 24, 2022 •

edited

sebasslash Feb 25, 2022

uturunku1 Feb 25, 2022 •

edited

brandonc Feb 24, 2022

sebasslash Feb 25, 2022

uturunku1 Feb 25, 2022

sebasslash Feb 25, 2022 •

edited

uturunku1 Feb 25, 2022

create consistency around godoc parsing #331

create consistency around godoc parsing #331

Conversation

uturunku1 commented Feb 24, 2022 • edited

Description

Testing plan

External links

Output from tests (HashiCorp employees only)

uturunku1 Feb 24, 2022 • edited

Choose a reason for hiding this comment

uturunku1 Feb 24, 2022

Choose a reason for hiding this comment

brandonc left a comment

Choose a reason for hiding this comment

brandonc Feb 24, 2022 • edited

Choose a reason for hiding this comment

sebasslash Feb 25, 2022

Choose a reason for hiding this comment

uturunku1 Feb 25, 2022 • edited

Choose a reason for hiding this comment

brandonc Feb 24, 2022

Choose a reason for hiding this comment

sebasslash Feb 25, 2022

Choose a reason for hiding this comment

uturunku1 Feb 25, 2022

Choose a reason for hiding this comment

sebasslash Feb 25, 2022 • edited

Choose a reason for hiding this comment

uturunku1 Feb 25, 2022

Choose a reason for hiding this comment

uturunku1 commented Feb 24, 2022 •

edited

uturunku1 Feb 24, 2022 •

edited

brandonc Feb 24, 2022 •

edited

uturunku1 Feb 25, 2022 •

edited

sebasslash Feb 25, 2022 •

edited