Lint godoc comments (#2972)

.golangci.yml

@@ -18,10 +18,13 @@ linters:
 linters-settings:
   gosec:
     excludes:
+      # duplicates errcheck
+      - G104
       # performance issue: see https://github.com/golangci/golangci-lint/issues/4039
       # and https://github.com/securego/gosec/issues/1007
       - G602
 issues:
+  exclude-use-default: false
   exclude-rules:
     - linters:
         - dupl
@@ -38,3 +41,13 @@ issues:
     # We need to use sha1 for validating signatures
     - linters: [ gosec ]
       text: 'G505: Blocklisted import crypto/sha1: weak cryptographic primitive'
+
+    # This is adapted from golangci-lint's default exclusions. It disables linting for error checks on
+    # os.RemoveAll and any function ending in "Close".
+    - linters: [ errcheck ]
+      text: Error return value of .(.*Close|os\.Remove(All)?). is not checked
+
+    # We don't care about file inclusion via variable in examples or internal tools.
+    - linters: [ gosec ]
+      text: 'G304: Potential file inclusion via variable'
+      path: '^(example|update-urls)\/'

github/actions_permissions_enterprise.go

@@ -10,7 +10,7 @@ import (
 	"fmt"
 )
 
-// ActionsEnabledOnEnterpriseOrgs represents all the repositories in an enterprise for which Actions is enabled.
+// ActionsEnabledOnEnterpriseRepos represents all the repositories in an enterprise for which Actions is enabled.
 type ActionsEnabledOnEnterpriseRepos struct {
 	TotalCount    int             `json:"total_count"`
 	Organizations []*Organization `json:"organizations"`

github/actions_permissions_orgs.go

@@ -145,7 +145,7 @@ func (s *ActionsService) AddEnabledReposInOrg(ctx context.Context, owner string,
 	return resp, nil
 }
 
-// RemoveEnabledRepoInOrg removes a single repository from the list of enabled repos for GitHub Actions in an organization.
+// RemoveEnabledReposInOrg removes a single repository from the list of enabled repos for GitHub Actions in an organization.
 //
 // GitHub API docs: https://docs.github.com/en/rest/actions/permissions#disable-a-selected-repository-for-github-actions-in-an-organization
 func (s *ActionsService) RemoveEnabledReposInOrg(ctx context.Context, owner string, repositoryID int64) (*Response, error) {

github/codesofconduct.go

@@ -46,7 +46,8 @@ func (s *CodesOfConductService) List(ctx context.Context) ([]*CodeOfConduct, *Re
 	return cs, resp, nil
 }
 
-// ListCodesOfConduct
+// ListCodesOfConduct returns all codes of conduct.
+//
 // Deprecated: Use CodesOfConductService.List instead
 func (c *Client) ListCodesOfConduct(ctx context.Context) ([]*CodeOfConduct, *Response, error) {
 	return c.CodesOfConduct.List(ctx)
@@ -74,7 +75,8 @@ func (s *CodesOfConductService) Get(ctx context.Context, key string) (*CodeOfCon
 	return coc, resp, nil
 }
 
-// GetCodeOfConduct
+// GetCodeOfConduct returns an individual code of conduct.
+//
 // Deprecated: Use CodesOfConductService.Get instead
 func (c *Client) GetCodeOfConduct(ctx context.Context, key string) (*CodeOfConduct, *Response, error) {
 	return c.CodesOfConduct.Get(ctx, key)

github/codespaces.go

@@ -112,7 +112,7 @@ func (s *CodespacesService) ListInRepo(ctx context.Context, owner, repo string,
 	return codespaces, resp, nil
 }
 
-// ListOptions represents the options for listing codespaces for a user.
+// ListCodespacesOptions represents the options for listing codespaces for a user.
 type ListCodespacesOptions struct {
 	ListOptions
 	RepositoryID int64 `url:"repository_id,omitempty"`

github/emojis.go

@@ -30,7 +30,8 @@ func (s *EmojisService) List(ctx context.Context) (map[string]string, *Response,
 	return emoji, resp, nil
 }
 
-// ListEmojis
+// ListEmojis returns the emojis available to use on GitHub.
+//
 // Deprecated: Use EmojisService.List instead
 func (c *Client) ListEmojis(ctx context.Context) (map[string]string, *Response, error) {
 	return c.Emojis.List(ctx)

github/event_types.go

@@ -1069,7 +1069,7 @@ type ArchivedAt struct {
 	To   *Timestamp `json:"to,omitempty"`
 }
 
-// ProjectsV2 represents an item belonging to a project.
+// ProjectV2Item represents an item belonging to a project.
 type ProjectV2Item struct {
 	ID            *int64     `json:"id,omitempty"`
 	NodeID        *string    `json:"node_id,omitempty"`

github/issues.go

@@ -303,7 +303,7 @@ func (s *IssuesService) Edit(ctx context.Context, owner string, repo string, num
 	return i, resp, nil
 }
 
-// Remove a milestone from an issue.
+// RemoveMilestone removes a milestone from an issue.
 //
 // This is a helper method to explicitly update an issue with a `null` milestone, thereby removing it.
 //

github/messages.go

@@ -326,7 +326,7 @@ func ParseWebHook(messageType string, payload []byte) (interface{}, error) {
 	return event.ParsePayload()
 }
 
-// WebhookTypes returns a sorted list of all the known GitHub event type strings
+// MessageTypes returns a sorted list of all the known GitHub event type strings
 // supported by go-github.
 func MessageTypes() []string {
 	types := make([]string, 0, len(eventTypeMapping))

github/meta.go

@@ -87,7 +87,8 @@ func (s *MetaService) Get(ctx context.Context) (*APIMeta, *Response, error) {
 	return meta, resp, nil
 }
 
-// APIMeta
+// APIMeta returns information about GitHub.com.
+//
 // Deprecated: Use MetaService.Get instead.
 func (c *Client) APIMeta(ctx context.Context) (*APIMeta, *Response, error) {
 	return c.Meta.Get(ctx)
@@ -117,7 +118,9 @@ func (s *MetaService) Octocat(ctx context.Context, message string) (string, *Res
 	return buf.String(), resp, nil
 }
 
-// Octocat
+// Octocat returns an ASCII art octocat with the specified message in a speech
+// bubble. If message is empty, a random zen phrase is used.
+//
 // Deprecated: Use MetaService.Octocat instead.
 func (c *Client) Octocat(ctx context.Context, message string) (string, *Response, error) {
 	return c.Meta.Octocat(ctx, message)
@@ -143,7 +146,8 @@ func (s *MetaService) Zen(ctx context.Context) (string, *Response, error) {
 	return buf.String(), resp, nil
 }
 
-// Zen
+// Zen returns a random line from The Zen of GitHub.
+//
 // Deprecated: Use MetaService.Zen instead.
 func (c *Client) Zen(ctx context.Context) (string, *Response, error) {
 	return c.Meta.Zen(ctx)

github/orgs_packages.go

@@ -10,7 +10,7 @@ import (
 	"fmt"
 )
 
-// List the packages for an organization.
+// ListPackages lists the packages for an organization.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#list-packages-for-an-organization
 func (s *OrganizationsService) ListPackages(ctx context.Context, org string, opts *PackageListOptions) ([]*Package, *Response, error) {
@@ -34,7 +34,7 @@ func (s *OrganizationsService) ListPackages(ctx context.Context, org string, opt
 	return packages, resp, nil
 }
 
-// Get a package by name from an organization.
+// GetPackage gets a package by name from an organization.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#get-a-package-for-an-organization
 func (s *OrganizationsService) GetPackage(ctx context.Context, org, packageType, packageName string) (*Package, *Response, error) {
@@ -53,7 +53,7 @@ func (s *OrganizationsService) GetPackage(ctx context.Context, org, packageType,
 	return pack, resp, nil
 }
 
-// Delete a package from an organization.
+// DeletePackage deletes a package from an organization.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#delete-a-package-for-an-organization
 func (s *OrganizationsService) DeletePackage(ctx context.Context, org, packageType, packageName string) (*Response, error) {
@@ -66,7 +66,7 @@ func (s *OrganizationsService) DeletePackage(ctx context.Context, org, packageTy
 	return s.client.Do(ctx, req, nil)
 }
 
-// Restore a package to an organization.
+// RestorePackage restores a package to an organization.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#restore-a-package-for-an-organization
 func (s *OrganizationsService) RestorePackage(ctx context.Context, org, packageType, packageName string) (*Response, error) {
@@ -79,7 +79,7 @@ func (s *OrganizationsService) RestorePackage(ctx context.Context, org, packageT
 	return s.client.Do(ctx, req, nil)
 }
 
-// Get all versions of a package in an organization.
+// PackageGetAllVersions gets all versions of a package in an organization.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#list-package-versions-for-a-package-owned-by-an-organization
 func (s *OrganizationsService) PackageGetAllVersions(ctx context.Context, org, packageType, packageName string, opts *PackageListOptions) ([]*PackageVersion, *Response, error) {
@@ -103,7 +103,7 @@ func (s *OrganizationsService) PackageGetAllVersions(ctx context.Context, org, p
 	return versions, resp, nil
 }
 
-// Get a specific version of a package in an organization.
+// PackageGetVersion gets a specific version of a package in an organization.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#get-a-package-version-for-an-organization
 func (s *OrganizationsService) PackageGetVersion(ctx context.Context, org, packageType, packageName string, packageVersionID int64) (*PackageVersion, *Response, error) {
@@ -122,7 +122,7 @@ func (s *OrganizationsService) PackageGetVersion(ctx context.Context, org, packa
 	return version, resp, nil
 }
 
-// Delete a package version from an organization.
+// PackageDeleteVersion deletes a package version from an organization.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#delete-package-version-for-an-organization
 func (s *OrganizationsService) PackageDeleteVersion(ctx context.Context, org, packageType, packageName string, packageVersionID int64) (*Response, error) {
@@ -135,7 +135,7 @@ func (s *OrganizationsService) PackageDeleteVersion(ctx context.Context, org, pa
 	return s.client.Do(ctx, req, nil)
 }
 
-// Restore a package version to an organization.
+// PackageRestoreVersion restores a package version to an organization.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#restore-package-version-for-an-organization
 func (s *OrganizationsService) PackageRestoreVersion(ctx context.Context, org, packageType, packageName string, packageVersionID int64) (*Response, error) {

github/rate_limit.go

@@ -58,7 +58,7 @@ func (r RateLimits) String() string {
 	return Stringify(r)
 }
 
-// RateLimits returns the rate limits for the current client.
+// Get returns the rate limits for the current client.
 func (s *RateLimitService) Get(ctx context.Context) (*RateLimits, *Response, error) {
 	req, err := s.client.NewRequest("GET", "rate_limit", nil)
 	if err != nil {

github/reactions.go

@@ -493,7 +493,7 @@ func (s *ReactionsService) deleteReaction(ctx context.Context, url string) (*Res
 	return s.client.Do(ctx, req, nil)
 }
 
-// Create a reaction to a release.
+// CreateReleaseReaction creates a reaction to a release.
 // Note that a response with a Status: 200 OK means that you already
 // added the reaction type to this release.
 // The content should have one of the following values: "+1", "-1", "laugh", "confused", "heart", "hooray", "rocket", or "eyes".

github/repos.go

@@ -1153,7 +1153,8 @@ type AllowForcePushes struct {
 	Enabled bool `json:"enabled"`
 }
 
-// RequiredConversationResolution, if enabled, requires all comments on the pull request to be resolved before it can be merged to a protected branch.
+// RequiredConversationResolution requires all comments on the pull request to be resolved before it can be
+// merged to a protected branch when enabled.
 type RequiredConversationResolution struct {
 	Enabled bool `json:"enabled"`
 }

github/repos_pages.go

@@ -286,7 +286,7 @@ func (s *RepositoriesService) RequestPageBuild(ctx context.Context, owner, repo
 	return build, resp, nil
 }
 
-// GetPagesHealthCheck gets a DNS health check for the CNAME record configured for a repository's GitHub Pages.
+// GetPageHealthCheck gets a DNS health check for the CNAME record configured for a repository's GitHub Pages.
 //
 // GitHub API docs: https://docs.github.com/en/rest/pages#get-a-dns-health-check-for-github-pages
 func (s *RepositoriesService) GetPageHealthCheck(ctx context.Context, owner, repo string) (*PagesHealthCheckResponse, *Response, error) {

github/repos_rules.go

@@ -48,7 +48,7 @@ type RulesetRepositoryIDsConditionParameters struct {
 	RepositoryIDs []int64 `json:"repository_ids,omitempty"`
 }
 
-// RulesetCondition represents the conditions object in a ruleset.
+// RulesetConditions represents the conditions object in a ruleset.
 // Set either RepositoryName or RepositoryID, not both.
 type RulesetConditions struct {
 	RefName        *RulesetRefConditionParameters             `json:"ref_name,omitempty"`

github/secret_scanning.go

@@ -90,7 +90,7 @@ type SecretScanningAlertUpdateOptions struct {
 	Resolution *string `json:"resolution,omitempty"`
 }
 
-// Lists secret scanning alerts for eligible repositories in an enterprise, from newest to oldest.
+// ListAlertsForEnterprise lists secret scanning alerts for eligible repositories in an enterprise, from newest to oldest.
 //
 // To use this endpoint, you must be a member of the enterprise, and you must use an access token with the repo scope or
 // security_events scope. Alerts are only returned for organizations in the enterprise for which you are an organization owner or a security manager.
@@ -117,7 +117,7 @@ func (s *SecretScanningService) ListAlertsForEnterprise(ctx context.Context, ent
 	return alerts, resp, nil
 }
 
-// Lists secret scanning alerts for eligible repositories in an organization, from newest to oldest.
+// ListAlertsForOrg lists secret scanning alerts for eligible repositories in an organization, from newest to oldest.
 //
 // To use this endpoint, you must be an administrator for the repository or organization, and you must use an access token with
 // the repo scope or security_events scope.
@@ -144,7 +144,7 @@ func (s *SecretScanningService) ListAlertsForOrg(ctx context.Context, org string
 	return alerts, resp, nil
 }
 
-// Lists secret scanning alerts for a private repository, from newest to oldest.
+// ListAlertsForRepo lists secret scanning alerts for a private repository, from newest to oldest.
 //
 // To use this endpoint, you must be an administrator for the repository or organization, and you must use an access token with
 // the repo scope or security_events scope.
@@ -171,7 +171,7 @@ func (s *SecretScanningService) ListAlertsForRepo(ctx context.Context, owner, re
 	return alerts, resp, nil
 }
 
-// Gets a single secret scanning alert detected in a private repository.
+// GetAlert gets a single secret scanning alert detected in a private repository.
 //
 // To use this endpoint, you must be an administrator for the repository or organization, and you must use an access token with
 // the repo scope or security_events scope.
@@ -194,7 +194,7 @@ func (s *SecretScanningService) GetAlert(ctx context.Context, owner, repo string
 	return alert, resp, nil
 }
 
-// Updates the status of a secret scanning alert in a private repository.
+// UpdateAlert updates the status of a secret scanning alert in a private repository.
 //
 // To use this endpoint, you must be an administrator for the repository or organization, and you must use an access token with
 // the repo scope or security_events scope.
@@ -217,7 +217,7 @@ func (s *SecretScanningService) UpdateAlert(ctx context.Context, owner, repo str
 	return alert, resp, nil
 }
 
-// Lists all locations for a given secret scanning alert for a private repository.
+// ListLocationsForAlert lists all locations for a given secret scanning alert for a private repository.
 //
 // To use this endpoint, you must be an administrator for the repository or organization, and you must use an access token with
 // the repo scope or security_events scope.

github/users_packages.go

@@ -10,7 +10,7 @@ import (
 	"fmt"
 )
 
-// List the packages for a user. Passing the empty string for "user" will
+// ListPackages lists the packages for a user. Passing the empty string for "user" will
 // list packages for the authenticated user.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#list-packages-for-the-authenticated-users-namespace
@@ -41,7 +41,7 @@ func (s *UsersService) ListPackages(ctx context.Context, user string, opts *Pack
 	return packages, resp, nil
 }
 
-// Get a package by name for a user. Passing the empty string for "user" will
+// GetPackage gets a package by name for a user. Passing the empty string for "user" will
 // get the package for the authenticated user.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#get-a-package-for-the-authenticated-user
@@ -68,7 +68,7 @@ func (s *UsersService) GetPackage(ctx context.Context, user, packageType, packag
 	return pack, resp, nil
 }
 
-// Delete a package from a user. Passing the empty string for "user" will
+// DeletePackage deletes a package from a user. Passing the empty string for "user" will
 // delete the package for the authenticated user.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#delete-a-package-for-the-authenticated-user
@@ -89,7 +89,7 @@ func (s *UsersService) DeletePackage(ctx context.Context, user, packageType, pac
 	return s.client.Do(ctx, req, nil)
 }
 
-// Restore a package to a user. Passing the empty string for "user" will
+// RestorePackage restores a package to a user. Passing the empty string for "user" will
 // restore the package for the authenticated user.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#restore-a-package-for-the-authenticated-user
@@ -110,7 +110,7 @@ func (s *UsersService) RestorePackage(ctx context.Context, user, packageType, pa
 	return s.client.Do(ctx, req, nil)
 }
 
-// Get all versions of a package for a user. Passing the empty string for "user" will
+// PackageGetAllVersions gets all versions of a package for a user. Passing the empty string for "user" will
 // get versions for the authenticated user.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#get-all-package-versions-for-a-package-owned-by-the-authenticated-user
@@ -141,7 +141,7 @@ func (s *UsersService) PackageGetAllVersions(ctx context.Context, user, packageT
 	return versions, resp, nil
 }
 
-// Get a specific version of a package for a user. Passing the empty string for "user" will
+// PackageGetVersion gets a specific version of a package for a user. Passing the empty string for "user" will
 // get the version for the authenticated user.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#get-a-package-version-for-the-authenticated-user
@@ -168,7 +168,7 @@ func (s *UsersService) PackageGetVersion(ctx context.Context, user, packageType,
 	return version, resp, nil
 }
 
-// Delete a package version for a user. Passing the empty string for "user" will
+// PackageDeleteVersion deletes a package version for a user. Passing the empty string for "user" will
 // delete the version for the authenticated user.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#delete-a-package-version-for-the-authenticated-user
@@ -189,7 +189,7 @@ func (s *UsersService) PackageDeleteVersion(ctx context.Context, user, packageTy
 	return s.client.Do(ctx, req, nil)
 }
 
-// Restore a package version to a user. Passing the empty string for "user" will
+// PackageRestoreVersion restores a package version to a user. Passing the empty string for "user" will
 // restore the version for the authenticated user.
 //
 // GitHub API docs: https://docs.github.com/en/rest/packages#restore-a-package-version-for-the-authenticated-user

github/users_ssh_signing_keys.go

@@ -93,7 +93,7 @@ func (s *UsersService) CreateSSHSigningKey(ctx context.Context, key *Key) (*SSHS
 	return k, resp, nil
 }
 
-// DeleteKey deletes a SSH signing key for the authenticated user.
+// DeleteSSHSigningKey deletes a SSH signing key for the authenticated user.
 //
 // GitHub API docs: https://docs.github.com/en/rest/users/ssh-signing-keys#delete-an-ssh-signing-key-for-the-authenticated-user
 func (s *UsersService) DeleteSSHSigningKey(ctx context.Context, id int64) (*Response, error) {